diff --git a/AGENTS.md b/AGENTS.md index 028cc194..089da5bb 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -190,7 +190,7 @@ The project version is fully independent of module versions. A module bump (even - `src/vendorlib_tcl9/` — Tcl 9 specific vendor libraries - `src/runtime/` — Build runtimes and VFS config (see src/runtime/AGENTS.md) - `src/doc/` — Generated documentation (see src/doc/AGENTS.md) - - `src/assets/logo/` — Project logo vector masters (`punk-mark.svg`, solid-plate alternate) and the multi-resolution `.ico` files generated from them; the icon MASTER, distinct from the build-consumed copies at `src/runtime/punk1.ico` and `src/vfs/_vfscommon.vfs/punk1.ico`. Retired artwork kept under `legacy/` (see src/assets/logo/AGENTS.md) + - `src/assets/logo/` — Project logo vector masters (`punk-mark.svg`, solid-plate alternate) and the multi-resolution `.ico` files generated from them; the icon MASTER, distinct from the build-consumed copies at `src/runtime/punkshell.ico` and `src/vfs/_vfscommon.vfs/punkshell.ico`. Retired pre-2026-07 artwork kept under `legacy/` as `punk1.*` - the only place that legacy name survives (see src/assets/logo/AGENTS.md) - `src/testansi/` — Sample ANSI art files (do not modify) - `bin/` — Built punk shell executables, launch package modes (incl. `src` mode for working-tree verification), plain runtime kits (see bin/AGENTS.md) - `.fossil-settings/` — Versioned fossil settings and the git+fossil dual-VCS coexistence contract: ignore-sync rules, files neither system may track (see .fossil-settings/AGENTS.md) diff --git a/GOALS.md b/GOALS.md index 79590b1f..d9f168a8 100644 --- a/GOALS.md +++ b/GOALS.md @@ -246,7 +246,7 @@ Scope: src/modules/punk/args-999999.0a1.0.tm (arg_error table and string rendere Detail: goals/G-056-punkargs-word-wrapping.md ### G-057 [proposed] Kit builds carry a configurable icon: text sidecar for every target, embedded PE resources for windows targets -Scope: src/make.tcl (kit/zipkit wrap steps); src/runtime/punk1.ico (project default, existing); src/vfs/*.vfs (override placement convention); src/runtime/mapvfs.config (only if an explicit config element is the chosen override mechanism); TEMP_REFERENCE/tcl-sfe (read-only reference); helper proc location decided in the work (make.tcl inline vs punk::mix lib); kit icon sidecar record (emission points recorded in the work) +Scope: src/make.tcl (kit/zipkit wrap steps); src/runtime/punkshell.ico (project default, existing); src/vfs/*.vfs (override placement convention); src/runtime/mapvfs.config (only if an explicit config element is the chosen override mechanism); TEMP_REFERENCE/tcl-sfe (read-only reference); helper proc location decided in the work (make.tcl inline vs punk::mix lib); kit icon sidecar record (emission points recorded in the work) Detail: goals/G-057-kit-icon-embedding.md ### G-060 [proposed] QEMU-based cross-platform test matrix (arm's-length integration, GPL-safe posture) diff --git a/goals/G-057-kit-icon-embedding.md b/goals/G-057-kit-icon-embedding.md index 49bea090..d7a18078 100644 --- a/goals/G-057-kit-icon-embedding.md +++ b/goals/G-057-kit-icon-embedding.md @@ -1,18 +1,25 @@ # G-057 Kit builds carry a configurable icon: text sidecar for every target, embedded PE resources for windows targets Status: proposed -Scope: src/make.tcl (kit/zipkit wrap steps); src/runtime/punk1.ico (project default, existing); src/vfs/*.vfs (override placement convention); src/runtime/mapvfs.config (only if an explicit config element is the chosen override mechanism); TEMP_REFERENCE/tcl-sfe (read-only reference); helper proc location decided in the work (make.tcl inline vs punk::mix lib); kit icon sidecar record (emission points recorded in the work) -Goal: kit/zipkit builds record a build-time icon choice for every target - defaulting to the project icon src/runtime/punk1.ico and overridable per kit by its .vfs folder - in a text sidecar that ships with the kit whatever its target, and embed it as PE icon resources when the target has them and the build host can write them - by replacing the icon resources in the built executable using the twapi-based mechanism demonstrated in tcl-sfe (TEMP_REFERENCE/tcl-sfe, by twapi author and Tcl core member Ashok P. Nadkarni): RT_ICON/RT_GROUP_ICON replacement via twapi resource-update APIs, applied so the appended vfs payload stays intact (icon the stub before appending, or sfe-style split/update/reattach), behind a single mechanism seam so the embedding implementation can be replaced without touching its callers. -Acceptance: a `make.tcl bake` on a windows host producing a win32-target kit produces kit executables whose embedded icon resources are the project default punk1.ico, and a kit whose .vfs supplies an override icon gets that icon instead (verified by resource inspection, e.g twapi::extract_resources, not just Explorer eyeballing); the icon-replaced executables still boot to a working punk shell reading their vfs payload for the kit types we build (kit, zip, zipcat per mapvfs.config); runtimes under src/runtime are never modified - replacement applies to the built copies only; a target with no PE resources (linux, freebsd, macosx) skips embedding as NOT APPLICABLE rather than as degradation and still gets its sidecar, while a win32 target on a host that cannot perform the update (twapi unavailable, or a non-windows host cross-baking a windows kit) skips embedding with a DISTINCT notice naming which condition applied, still writes the sidecar, and the build otherwise completes unchanged - the cross-host case is recorded here as a known shortcoming with its remedy; the sidecar is produced for every kit on every target, carries the same icon data the PE embedding uses (source .ico identity and provenance) in a documented plain-text form, is byte-stable across rebuilds at unchanged input, and is defined so the parked RT_VERSION follow-on extends the same file rather than adding a second one; the embedding implementation sits behind a single internal entry point with the mechanism selected inside it, so a later portable replacement is a substitution rather than a rewrite; the twapi mechanism remains available INDEFINITELY as the no-toolchain windows path - the seam SELECTS between mechanisms rather than replacing one with the other - and a fresh checkout that fetches a runtime and bakes produces iconed kits with no build toolchain installed; rebuilds are idempotent (re-wrapping an already-iconed build copy converges, no resource accumulation); the override convention (filename/location in the kit's custom .vfs folder vs a mapvfs.config element) and the stub-vs-split ordering decision are recorded in the detail file with the tcl-sfe attribution - the override is SHARED across a kit definition's targets and carries no target dimension (decided 2026-07-26): it is used where embedding applies and ignored elsewhere. +Scope: src/make.tcl (kit/zipkit wrap steps); src/runtime/punkshell.ico (project default, existing); src/vfs/*.vfs (override placement convention); src/runtime/mapvfs.config (only if an explicit config element is the chosen override mechanism); TEMP_REFERENCE/tcl-sfe (read-only reference); helper proc location decided in the work (make.tcl inline vs punk::mix lib); kit icon sidecar record (emission points recorded in the work) +Goal: kit/zipkit builds record a build-time icon choice for every target - defaulting to the project icon src/runtime/punkshell.ico and overridable per kit by its .vfs folder - in a text sidecar that ships with the kit whatever its target, and embed it as PE icon resources when the target has them and the build host can write them - by replacing the icon resources in the built executable using the twapi-based mechanism demonstrated in tcl-sfe (TEMP_REFERENCE/tcl-sfe, by twapi author and Tcl core member Ashok P. Nadkarni): RT_ICON/RT_GROUP_ICON replacement via twapi resource-update APIs, applied so the appended vfs payload stays intact (icon the stub before appending, or sfe-style split/update/reattach), behind a single mechanism seam so the embedding implementation can be replaced without touching its callers. +Acceptance: a `make.tcl bake` on a windows host producing a win32-target kit produces kit executables whose embedded icon resources are the project default punkshell.ico, and a kit whose .vfs supplies an override icon gets that icon instead (verified by resource inspection, e.g twapi::extract_resources, not just Explorer eyeballing); the icon-replaced executables still boot to a working punk shell reading their vfs payload for the kit types we build (kit, zip, zipcat per mapvfs.config); runtimes under src/runtime are never modified - replacement applies to the built copies only; a target with no PE resources (linux, freebsd, macosx) skips embedding as NOT APPLICABLE rather than as degradation and still gets its sidecar, while a win32 target on a host that cannot perform the update (twapi unavailable, or a non-windows host cross-baking a windows kit) skips embedding with a DISTINCT notice naming which condition applied, still writes the sidecar, and the build otherwise completes unchanged - the cross-host case is recorded here as a known shortcoming with its remedy; the sidecar is produced for every kit on every target, carries the same icon data the PE embedding uses (source .ico identity and provenance) in a documented plain-text form, is byte-stable across rebuilds at unchanged input, and is defined so the parked RT_VERSION follow-on extends the same file rather than adding a second one; the embedding implementation sits behind a single internal entry point with the mechanism selected inside it, so a later portable replacement is a substitution rather than a rewrite; the twapi mechanism remains available INDEFINITELY as the no-toolchain windows path - the seam SELECTS between mechanisms rather than replacing one with the other - and a fresh checkout that fetches a runtime and bakes produces iconed kits with no build toolchain installed; rebuilds are idempotent (re-wrapping an already-iconed build copy converges, no resource accumulation); the override convention (filename/location in the kit's custom .vfs folder vs a mapvfs.config element) and the stub-vs-split ordering decision are recorded in the detail file with the tcl-sfe attribution - the override is SHARED across a kit definition's targets and carries no target dimension (decided 2026-07-26): it is used where embedding applies and ignored elsewhere. ## Context Built punk kit executables currently carry whatever icon resource their runtime -stub shipped with. The project icon src/runtime/punk1.ico exists and is COPIED +stub shipped with. The project icon src/runtime/punkshell.ico exists and is COPIED into vfs trees (a tclkit-era convention), but nothing embeds it into the produced executable's Windows resources - so all kits look like their runtime in Explorer and the taskbar. +Renamed 2026-07-28 from punk1.ico, and its artwork replaced from the +src/assets/logo/ master at the same time. The four build-consumed copies +(src/runtime/, _vfscommon.vfs, mkzipfix.vfs, punk8_statictwapi.vfs) are now +punkshell.ico and are copies of src/assets/logo/punk-mark.ico; the pre-2026-07 +punk1 artwork is retained at src/assets/logo/legacy/ and is the only place that +name survives. + Host/target reopened this (2026-07-26). The goal was drafted before G-122 separated what the driving tclsh IS from what a bake is FOR, so its skip condition read as one host-shaped test ("non-Windows platform") while its Notes used target language @@ -43,9 +50,9 @@ image directory. sfe approach of splitting payload off, updating resources, and reattaching (sfe-0.2.tm does the split/update/reattach dance for exactly this reason). Chosen ordering to be recorded here. -- Default icon: src/runtime/punk1.ico. Per-kit override supplied by the kit's +- Default icon: src/runtime/punkshell.ico. Per-kit override supplied by the kit's .vfs. IMPORTANT wrinkle for the override convention: _vfscommon.vfs already - merges a punk1.ico into every built vfs tree, so override detection must + merges a punkshell.ico into every built vfs tree, so override detection must consult the kit's own CUSTOM .vfs folder (pre-merge, under src/vfs/) - or use an explicit mapvfs.config element - otherwise every kit would appear to "override" with the same common file. Chosen convention to be recorded here. diff --git a/src/assets/logo/AGENTS.md b/src/assets/logo/AGENTS.md index b773e725..080b893d 100644 --- a/src/assets/logo/AGENTS.md +++ b/src/assets/logo/AGENTS.md @@ -3,7 +3,7 @@ ## Purpose Holds the vector masters for the punkshell logo and the `.ico` files generated -from them. This directory is the SOURCE of the project icon; every `punk1.ico` +from them. This directory is the SOURCE of the project icon; every `punkshell.ico` elsewhere in the tree is a derived copy or a build input, never an original. ## Ownership @@ -13,9 +13,12 @@ elsewhere in the tree is a derived copy or a build input, never an original. - Files under `legacy/` are retired artwork kept for provenance. Do not edit, regenerate, or "modernise" them; they record what shipped before. - Do not repoint build consumers at this directory on your own initiative. The - icon actually consumed by builds still lives at `src/runtime/punk1.ico` (the - G-057 default) and `src/vfs/_vfscommon.vfs/punk1.ico`; swapping those is a - user-directed step. + icon consumed by builds lives at `src/runtime/punkshell.ico` (the G-057 + default) and `src/vfs/_vfscommon.vfs/punkshell.ico`, plus per-kit copies under + `src/vfs/mkzipfix.vfs/` and `src/vfs/punk8_statictwapi.vfs/`. Those four were + set from `punk-mark.ico` on 2026-07-28 at the user's direction. Propagating a + later change to them is build machinery owned by G-057 — not a manual step to + repeat from here. ## Local Contracts @@ -43,6 +46,15 @@ elsewhere in the tree is a derived copy or a build input, never an original. regenerate with a DIB 256 entry (see Work Guidance) instead of assuming the file is at fault. +- **`project-default/` is FROZEN placeholder artwork, not a treatment of the + mark.** It is the default icon a generated project starts with: a blank screen + wearing the crest, monochrome and deliberately unbranded so it reads "replace + me" rather than as a product identity. It shares only the crest with + `punk-mark.svg` and must NOT be re-derived from it — if it tracked the real + mark, every logo tweak would churn every generated project. Its bezel and + crest are one union path (drawn as two shapes, the bezel's top edge cuts a + line across the mohawk) and its screen is filled rather than outlined (a solid + mass survives 16px where nested thin strokes merge). - **`web/` is a separate build with different rules.** Its `favicon.ico` is 16/32/48 and ALL-PNG (2.5KB, since it is fetched on every cold page load); that file is web-only and must never be used as a PE resource. `web/icon.svg` @@ -97,5 +109,6 @@ elsewhere in the tree is a derived copy or a build input, never an original. ## Child DOX Index - `alternative/` — Solid-plate treatment of the same mark (covered by this file) +- `project-default/` — Frozen monochrome placeholder seeded into generated projects; single held copy, no artwork in layout payload trees (covered by this file) - `web/` — Favicon/webmanifest set for website use; theme-aware `icon.svg`, all-PNG `favicon.ico`, opaque apple-touch and PWA rasters (covered by this file) - `legacy/` — Retired pre-2026-07 artwork, provenance only (covered by this file) diff --git a/src/assets/logo/project-default/icon.ico b/src/assets/logo/project-default/icon.ico new file mode 100644 index 00000000..1ba43bd8 Binary files /dev/null and b/src/assets/logo/project-default/icon.ico differ diff --git a/src/assets/logo/project-default/icon.svg b/src/assets/logo/project-default/icon.svg new file mode 100644 index 00000000..e45172da --- /dev/null +++ b/src/assets/logo/project-default/icon.svg @@ -0,0 +1,29 @@ + + project placeholder + + + + diff --git a/src/runtime/punk1.ico b/src/runtime/punk1.ico deleted file mode 100644 index dac43134..00000000 Binary files a/src/runtime/punk1.ico and /dev/null differ diff --git a/src/runtime/punkshell.ico b/src/runtime/punkshell.ico new file mode 100644 index 00000000..f0c95aee Binary files /dev/null and b/src/runtime/punkshell.ico differ diff --git a/src/vfs/_vfscommon.vfs/punk1.ico b/src/vfs/_vfscommon.vfs/punk1.ico deleted file mode 100644 index dac43134..00000000 Binary files a/src/vfs/_vfscommon.vfs/punk1.ico and /dev/null differ diff --git a/src/vfs/_vfscommon.vfs/punkshell.ico b/src/vfs/_vfscommon.vfs/punkshell.ico new file mode 100644 index 00000000..f0c95aee Binary files /dev/null and b/src/vfs/_vfscommon.vfs/punkshell.ico differ diff --git a/src/vfs/mkzipfix.vfs/punk1.ico b/src/vfs/mkzipfix.vfs/punk1.ico deleted file mode 100644 index dac43134..00000000 Binary files a/src/vfs/mkzipfix.vfs/punk1.ico and /dev/null differ diff --git a/src/vfs/mkzipfix.vfs/punkshell.ico b/src/vfs/mkzipfix.vfs/punkshell.ico new file mode 100644 index 00000000..f0c95aee Binary files /dev/null and b/src/vfs/mkzipfix.vfs/punkshell.ico differ diff --git a/src/vfs/punk8_statictwapi.vfs/punk1.ico b/src/vfs/punk8_statictwapi.vfs/punk1.ico deleted file mode 100644 index dac43134..00000000 Binary files a/src/vfs/punk8_statictwapi.vfs/punk1.ico and /dev/null differ diff --git a/src/vfs/punk8_statictwapi.vfs/punkshell.ico b/src/vfs/punk8_statictwapi.vfs/punkshell.ico new file mode 100644 index 00000000..f0c95aee Binary files /dev/null and b/src/vfs/punk8_statictwapi.vfs/punkshell.ico differ