gina 0.5.23 → 0.5.24

package/CHANGELOG.md

@@ -6,6 +6,18 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html),
 and is generated by [Changie](https://github.com/miniscruff/changie).
 
 
+## 0.5.24 - 2026-07-22
+### Added
+* A per-upload-group `simulateWriteError` flag (honoured outside production scope only) deterministically triggers the multipart write-error path, so you can confirm the guarded-500 crash-guard on your own upload surface after an upgrade — with no filesystem or global-config change that affects real uploads. A group carrying the flag makes every upload tagging it answer HTTP 500 (the same guarded response a real mid-stream write error produces), and a boot warning surfaces the flag if it is ever shipped to production, where it stays inert. Server-side only — restart your bundles to pick it up.
+* Upload progress for the staged upload client layer (#R8, slice 1): the staging POST of a `data-gina-form-upload-*` file input now reports real client-to-server wire progress via `xhr.upload.onprogress`. A new registered form event `uploadProgress.<uploadFormId>` carries `{ status, progress, loaded, total, lengthComputable, files }` (per-request aggregate: one staging request carries every file of a selection). Opt-in consumer surfaces: `data-gina-form-upload-on-progress="<windowCallback>"` (bare identifier, the `-on-success` convention) and a declarative indicator resolved from `data-gina-form-upload-progress="<elementId>"` or the default `<fieldId>-progress` (the `-preview`/`-error` family convention) — a native `<progress>` element tracks uploaded/total bytes with native indeterminate handling, any other element gets a percent text plus `data-gina-upload-progress` / `data-gina-upload-progress-state` styling hooks; the full lifecycle is managed (preparing at selection, uploading, complete, error empties the bar, reset/delete strips the indicator) and no wording is hardcoded. The response-side download progress channel is untouched. Browser-bundled: consumers pick this up with a bundle re-bake.
+* Drag-and-drop for the staged upload client layer (#R8): a file input carrying `data-gina-form-upload-dropzone="<elementId>"` binds the named element as a dropzone — files dropped there route through the exact same staging pipeline as a native picker selection (group tagging, staging POST, previews, hidden metadata fields, reset/delete and upload progress). Opt-in and explicit-id-only (no default id resolution), first-wins per zone, only file drags react (text/link drags fall through untouched), and a multi-file drop on a non-`multiple` input keeps the first file with a console warning. The dropzone element carries `data-gina-upload-dropzone` (owner input id) and `data-gina-upload-dropzone-state` (`idle`/`over`/`dropped`) as pure CSS styling hooks — no hardcoded wording.
+* Incident ref on error responses: every `throwError` JSON error body now carries a top-level `ref` field - a short voice-relayable correlation code (6 uppercase hex, or a relay-safe caller-supplied value), present in ALL scopes - and ONE server-side error-level log line pairs that ref with the full error detail (message + stack + cause) plus the request correlation id BEFORE the stack-egress gate strips the wire copy, so support can resolve a user-relayed ref to the exact server-side failure even in production. The HTML error surfaces (custom error page data and the inline fallback page) carry the same ref. Also closes two logging gaps: a production API error thrown through the controller previously lost its stack server-side entirely (stripped before the only log line), and message-only server errors logged method/code/url without the message. Always-on, additive and backward-compatible - consumers parsing status/error are unaffected until they adopt the ref.
+### Fixed
+* A misconfigured upload group whose destination directory cannot be created (a read-only or permission-denied parent) now answers HTTP 500 for that one request instead of crashing the bundle; previously the synchronous directory-creation error inside the multipart parser propagated as an uncaught exception and terminated the process on the next upload tagging that group.
+* The staged upload client layer (`data-gina-form-upload-*`) no longer corrupts binary file uploads: the multipart body was hand-assembled as a JS string and transmitted as a DOMString, which UTF-8-inflated every file byte >= 0x80 on the wire — a real image/PDF/archive was stored inflated and unreadable (measured x1.49 on a cycling-byte fixture; a PNG lost its signature). The body is now assembled as a Blob (raw file bytes, transmitted verbatim) with the multipart framing and the `group=` disposition parameter byte-identical to before — no server or wire-contract change; disposition parameter values additionally percent-encode CR/LF/double-quote per RFC 7578 (an unescaped quote previously produced a malformed part). Files corrupted by this defect are losslessly recoverable: the stored bytes are exactly the UTF-8 encoding of the original (decode utf8, re-encode latin1). NOTE the corruption only surfaced on gina >= 0.5.22 — the pre-0.5.22 server's since-removed string-decode layers coincidentally reversed the client inflation, so older round-trips were byte-clean. Browser-bundled: consumers pick the fix up with a bundle re-bake, paired with a server >= 0.5.22.
+* Staged file uploads: a file input that declares only its upload action (data-gina-form-upload-action) is no longer silently repointed at the reset/delete route. When a reset- or delete-action attribute was absent and a default route resolved, the fallback wrote the resolved URL onto the staging action attribute regardless of which attribute it was checking, so the staging POST went to the delete route. The fallback now writes the attribute it was actually checking. This is browser-bundled - rebuild your bundles (re-bake) to pick it up.
+* Staged file uploads: an upload no longer throws in its success handler when no preview element is present. The preview-container lookup treated a getElementById miss (null) as a real element, stored it, and later dereferenced it; it now requires a resolved element, so an upload configured without a preview target completes cleanly. This is browser-bundled - rebuild your bundles (re-bake) to pick it up.
+
 ## 0.5.23 - 2026-07-21
 ### Fixed
 * Fixed `req.files[].size` under-counting on multipart uploads — the value was snapshotted while the write pipeline could still hold uncounted chunks, so it came up short by a varying whole-chunk amount (file bytes on disk were always intact; only the reported number was wrong). The count is now finalized once the last chunk has been counted — strictly before the request resumes — so `req.files[].size`, and anything persisting it (e.g. via `self.store()`), reflects the exact stored byte size.

package/README.md

@@ -59,11 +59,16 @@ open https://localhost:3100
 
 > **npm 12+** blocks install scripts by default, and gina's post-install bootstraps `~/.gina` and the framework dependencies. Install with `npm install -g gina@latest --allow-scripts=gina`, or allow it once for all global installs with `npm config set allow-scripts=gina --location=user`. (Not needed on npm ≤ 11.)
 
-## What's in 0.5.23
-
-- **Fixed — `req.files[].size` reports the exact stored byte count on multipart uploads.** The size was snapshotted while the write pipeline could still hold chunks it had not yet counted, so it came back short by a varying whole-chunk amount — the file bytes on disk were always intact and complete, only the reported number was wrong. The count is now finalized once the last chunk has been counted, strictly before the request resumes, so `req.files[].size` — and anything that persists it, e.g. the `self.store()` result's `size` — reflects the real on-disk byte size. Server-side — restart your bundles. (#B142)
-- **Fixed — a multi-file multipart upload no longer hangs.** A request carrying two or more file parts never resumed when an early small file finished writing while a later, larger part was still streaming: the request produced no response and no log line until a client or front-proxy timeout. The per-stream completion listeners were attached only after the whole body was parsed, and a stream that had already finished never re-emits its completion event — so the early finisher's completion was lost and the request stalled forever (slow client connections hit this deterministically, fast ones intermittently). They now arm the moment each file stream is created, and the request resumes once the parse and every file write have both completed, in any order. A write error during streaming — a missing upload directory, a full disk — now answers a guarded 500 instead of crashing the bundle. Single-file uploads were never affected. Server-side — restart your bundles. (#B143)
-- **Fixed — the stale-release banner is injected on bundles using a custom async template loader.** A bundle configured with an async template loader (`settings.template.<engine>.loader`) doing a local production rehearsal with `server.releaseWatch` enabled got the `/_gina/release/*` endpoints and the SSE event stream but no in-page banner — the client banner was spliced in only on the synchronous render paths. Both async render delegates (swig and nunjucks) now inject the banner onto the finalized HTML exactly like the synchronous delegates, carrying the per-request CSP nonce when `useNonce` is active. The injector is unchanged and stays byte-inert on any request outside the release-watch gate. Server-side — restart your bundles. (#RWATCH)
+## What's in 0.5.24
+
+- **Added — upload progress for the staged upload client layer (#R8, slice 1).** The staging POST of a `data-gina-form-upload-*` file input now reports real client-to-server wire progress. A new registered form event `uploadProgress.<uploadFormId>` carries `{ status, progress, loaded, total, lengthComputable, files }` (per-request aggregate — one staging request carries every file of a selection). Opt-in consumer surfaces: `data-gina-form-upload-on-progress="<windowCallback>"` and a declarative indicator resolved from `data-gina-form-upload-progress="<elementId>"` or the default `<fieldId>-progress` — a native `<progress>` element tracks uploaded/total bytes, any other element gets percent text plus `data-gina-upload-progress` / `data-gina-upload-progress-state` styling hooks. No wording is hardcoded. Browser-bundled — re-bake your bundles. (#R8)
+- **Added — drag-and-drop for the staged upload client layer (#R8, slice 2).** A file input carrying `data-gina-form-upload-dropzone="<elementId>"` binds the named element as a dropzone; files dropped there route through the exact same staging pipeline as a native picker selection (group tagging, staging POST, previews, hidden metadata fields, reset/delete, and upload progress). Opt-in and explicit-id-only, first-wins per zone, only file drags react (text/link drags fall through untouched), and a multi-file drop on a non-`multiple` input keeps the first file with a console warning. The zone exposes `data-gina-upload-dropzone` (owner input id) and `data-gina-upload-dropzone-state` (`idle`/`over`/`dropped`) as pure CSS styling hooks. Browser-bundled — re-bake your bundles. (#R8)
+- **Added — incident ref on error responses (#ERRREF).** Every `throwError` JSON error body now carries a top-level `ref` field — a short voice-relayable correlation code (6 uppercase hex, or a relay-safe caller-supplied value), present in all scopes — and one server-side error-level log line pairs that ref with the full error detail (message, stack, cause) and the request correlation id before the stack-egress gate strips the wire copy, so support can resolve a user-relayed ref to the exact server-side failure even in production. The HTML error surfaces carry the same ref. Also closes two logging gaps: a production API error thrown through the controller previously lost its stack server-side entirely, and message-only server errors logged method/code/url without the message. Always-on, additive and backward-compatible. Server-side — restart your bundles. (#ERRREF)
+- **Added — a per-upload-group `simulateWriteError` flag (honoured outside production only) to verify the upload write-error crash-guard.** Setting it on an upload group makes every upload tagging that group deterministically answer the same guarded HTTP 500 a real mid-stream write error produces — so you can confirm the crash-guard on your own upload surface after an upgrade, with no filesystem or global-config change affecting real uploads. A boot warning surfaces the flag if it ever reaches production, where it stays inert. Server-side — restart your bundles. (#B144)
+- **Fixed — the staged upload client layer no longer corrupts binary file uploads.** The multipart body was hand-assembled as a JS string and transmitted as a DOMString, which UTF-8-inflated every file byte ≥ 0x80 on the wire — a real image/PDF/archive was stored inflated and unreadable (measured ×1.49 on a cycling-byte fixture; a PNG lost its signature). The body is now assembled as a Blob (raw file bytes, transmitted verbatim) with the multipart framing and the `group=` disposition parameter byte-identical to before — no server or wire-contract change; disposition parameter values additionally percent-encode CR/LF/double-quote per RFC 7578. Files corrupted by this defect are losslessly recoverable (the stored bytes are the UTF-8 encoding of the original: decode utf8, re-encode latin1). NOTE the corruption only surfaced on gina ≥ 0.5.22 — the pre-0.5.22 server's since-removed string-decode layers coincidentally reversed the client inflation. Browser-bundled — re-bake your bundles, paired with a server ≥ 0.5.22. (#B148)
+- **Fixed — a misconfigured upload group whose destination directory cannot be created now answers HTTP 500 for that one request instead of crashing the bundle.** Previously the synchronous directory-creation error inside the multipart parser propagated as an uncaught exception and terminated the process on the next upload tagging that group. Server-side — restart your bundles. (#B145)
+- **Fixed — a staged file input declaring only its upload action is no longer silently repointed at the reset/delete route.** When a reset- or delete-action attribute was absent and a default route resolved, the fallback wrote the resolved URL onto the staging action attribute regardless of which attribute it was checking, so the staging POST went to the delete route; it now writes the attribute it was actually checking. Browser-bundled — re-bake your bundles. (#B146)
+- **Fixed — an upload no longer throws in its success handler when no preview element is present.** The preview-container lookup treated a `getElementById` miss (null) as a real element, stored it, and later dereferenced it; it now requires a resolved element, so an upload configured without a preview target completes cleanly. Browser-bundled — re-bake your bundles. (#B147)
 
 See the full [Changelog](./CHANGELOG.md) and [Roadmap](./ROADMAP.md).
 

package/ROADMAP.md

@@ -48,6 +48,7 @@ This roadmap covers planned features, architectural improvements, new connectors
 | **Q3 2026** | `0.5.21` ✅ | **Security**: server-side error responses no longer serialize stack traces to HTTP clients outside local scope — the responder logs the full stack server-side and ships the message line only (JSON bodies, the inline HTML fallback, custom-error-page data; local scope keeps the development-toolbar stack) · **Changed**: a bundle whose `config/routing.json` is missing at boot now refuses to start with an error naming the bundle and environment (previously a silent half-boot with only the framework-synthetic routes; an external supervisor's restart retries until the release tree settles — the daemon itself is fail-stop), and the route-lookup not-found error names the bundle and its rule count · **Fixed**: FormValidator — modifier chords (Cmd/Ctrl+A/C/V/X/Z) run their native defaults again on `autocomplete="off"` live-check fields, the Safari-autocomplete interception gates on real Safari only (Chromium UAs no longer intercepted), and a whole-form live-check pass that turns valid clears every previously-errored field's message (#B134/#B135/#B136) · **Fixed**: merged-process (same-port multi-bundle) projects — the first cross-bundle getUrl no longer permanently replaces the target bundle's routing table with the starting app's, which rendered every cross-bundle link as a literal `404:[…]` marker; distinct-port projects were never affected (#B137) · **Fixed**: CSP `useNonce` on cache-enabled routes — the header and inline-bootstrap nonces now match and rotate per response, on cache hits and misses alike · **Fixed**: the env template's hardcoded `accept-language` response header is gone (a request header, wrongly emitted on every response) · **Added**: popin eager preload — `data-gina-dialog-preload="eager"` warms a popin's AJAX content at browser idle after window load, same safety gates as the hover/focus warm, skipped under Save-Data |
 | **Q3 2026** | `0.5.22` ✅ | **Fixed**: multipart binary uploads arrive byte-identical — file payloads are no longer string-decoded on their way to disk, so images, PDFs and archives stop arriving mangled and mis-sized (pure-ASCII payloads were unaffected, which is what hid it), and `req.files[].size` reports the real on-disk byte count (#B103) · link HTML callbacks work and no longer break the link — `data-gina-link-event-on-success` / `-on-error` used to make every click throw before the request was opened, leaving a dead link; both attributes now fire a `window`-level function with `(event, result)`, the programmatic `gina.link.on()` channel unchanged (#B141) · reopening an AJAX popin renders current content instead of the previous open's — the content cache now dies with the open it warmed, and `data-gina-dialog-preload="false"` becomes a hard always-refetch guarantee (#B139) · FormValidator — numbered `is<N>` rules keep their distinct error keys on re-validation instead of collapsing onto a doubled bare `is` (#B138), a `query` rule failure can no longer hang the submit pass (#B87), and the #49 checkbox migration warnings name the payload-only remedy and can be silenced per form (#B125) · `page.view.locale` carries the real country record instead of an empty object (#B101) · `npm install -g gina` no longer dies when the effective npm prefix contains a path segment npm's redactor masks (#B126) · **Added**: the `settings.i18n.cultures` allowlist is honoured — a non-empty array constrains which cultures the user-signal negotiation steps may match, so a shipped-but-unlaunched catalog stays unreachable until listed; the whole `i18n` block is now in the published schema · **Changed**: runtime pins moved to the standard `engines` manifest key, so unsupported runtimes finally get npm's `EBADENGINE` warning |
 | **Q3 2026** | `0.5.23` ✅ | **Fixed**: multipart `req.files[].size` now reports the exact stored byte count — the value was snapshotted before the write pipeline finished counting, coming up a varying whole-chunk short (file bytes on disk were always intact); it is finalized before the request resumes, so `self.store()` and any persister see the real size (#B142) · a multi-file multipart upload no longer hangs when an early small file finishes while a later large part is still streaming — the per-stream completion listeners now arm at creation (an already-finished stream's event never replays), and a mid-stream write error answers a guarded 500 instead of crashing the bundle; single-file uploads were unaffected (#B143) · the stale-release banner (`server.releaseWatch`) is now injected by the async template-loader render delegates too — a bundle on a custom async loader got the `/_gina/release/*` endpoints and SSE but no in-page banner; both async delegates (swig / nunjucks) now splice it onto the finalized HTML like the sync paths, CSP-nonce-aware, byte-inert outside the gate (#RWATCH) |
+| **Q3 2026** | `0.5.24` ✅ | **Added**: upload progress for the staged upload client layer — the staging POST reports real client-to-server wire progress via a new `uploadProgress.<id>` form event and an opt-in declarative `<progress>` / percent indicator (#R8, slice 1) · drag-and-drop — a file input binds a named element as a dropzone that routes dropped files through the exact same staging pipeline as the native picker, opt-in and explicit-id-only with `idle`/`over`/`dropped` CSS state hooks (#R8, slice 2) · an incident `ref` on every error response — a short voice-relayable correlation code (present in all scopes) that a server-side log line pairs with the full error detail before the wire copy is stripped, so support can resolve a user-relayed ref to the exact failure even in production (#ERRREF) · a per-upload-group `simulateWriteError` flag (non-production only) to verify the upload write-error crash-guard on your own surface after an upgrade (#B144) · **Fixed**: the staged upload client layer no longer corrupts binary uploads — the multipart body is now a Blob of raw file bytes instead of a UTF-8-inflating DOMString, so images / PDFs / archives are stored byte-identical (the defect only surfaced on gina ≥ 0.5.22; corrupted files are losslessly recoverable) (#B148) · a misconfigured upload group whose destination directory cannot be created answers a guarded 500 instead of crashing the bundle (#B145) · a file input declaring only its upload action is no longer silently repointed at the reset/delete route (#B146) · an upload no longer throws in its success handler when no preview element is present (#B147) |
 | **Q4 2026** | `0.6.0` | Security & compliance controls (technical safeguards mapping to PCI-DSS / SOC2 / HIPAA) |
 | **Q1 2027** | `0.5.x` | HTTP/2 priorities (blocked on Node scheduler hooks) · Beemaster admin + visual translation editor |
 | **Q3 2027** | `1.0.0` | First stable release — Windows alpha compatibility is a hard gate |
@@ -69,6 +70,7 @@ This roadmap covers planned features, architectural improvements, new connectors
 | ✅ | **Client-side components (Web Components)** — Standards-based conventions for stateful client widgets: custom elements v1, zero dependency, no build tooling. Server-rendered light-DOM authoring keeps HTML (designer) and JS (developer) separated — the behavior-only class binds its own server-rendered subtree and holds no markup strings (repeatable markup clones from a server-rendered `<template>`). Components upgrade automatically in popin/XHR-injected content with no rebinding; SEO/GEO-first (meaningful content ships in the initial server-rendered HTML). `gina view:add` scaffolds a reference component (engine partial + behavior-only class); e2e coverage locks popin auto-upgrade, strict-CSP compatibility (real nonce'd header, no `unsafe-inline`), SSR hydration from attributes + a JSON `data-*` payload, and no-JS crawler equivalence. The `gina-*` tag prefix is reserved for framework components. Form-associated custom elements participate in FormValidator — a named component exposing a `.value` getter is collected, validated, serialized into the AJAX payload, and error-rendered like a native control (client-side live-check on its composed bubbling `change`, dirty-tracking, and auto-id), so long as it declares `static formAssociated = true`, carries a `name`, and fires a composed `change` on commit. Live-data components ride the same lifecycle — open the connection in `connectedCallback`, close it in `disconnectedCallback` (popin close then tears it down automatically) — paired with `method:"ws"` routes or SSE via `renderStream()`, with per-animation-frame batching guidance for high-frequency streams; the lifecycle contract is executed against a live HTTP/2 extended-CONNECT loopback in the test suite. Dev-mode Inspector observability: the View tab carries a component census with a red undefined-components indicator (a typo'd tag or a missing definition script is no longer a silent failure), and the Events tab surfaces client-side `<tag>:<verb>` component events — metadata always, `detail` values only behind the existing `inspector.events.captureArgs` opt-in. | `0.5.15` | 2026-07-11 |
 | ✅ | **Stale built-release watch** — For LOCAL production rehearsals. A bundle serving a built release under `local` scope + a non-dev env has no hot-reload, so after you edit source it silently keeps serving the stale build. Opt in via `server.releaseWatch` in `settings.json`: the bundle watches its SOURCE tree, compares fingerprints against the manifest release stamp, and surfaces staleness on `GET /_gina/release/status` and a live `GET /_gina/release/events` SSE stream (notify mode, the default) — or auto-rebuilds on change (opt-in `auto` mode). `POST /_gina/release/rebuild` rebuilds with an **idle-gated restart** that waits on in-flight HTTP requests and `gina.registerBusyProbe` application probes, so a restart never interrupts in-flight work. Hard-gated on `local` scope + a non-dev env — never active on a real cluster. | `0.5.18-alpha` | 2026-07-16 |
 | ✅ | **Popin eager preload** — Opt-in idle warming for AJAX popin content. Mark a trigger with `data-gina-dialog-preload="eager"` (case-insensitive) and the popin plugin fetches its content after `window` load, at browser idle — one trigger at a time, off the critical path — so opening feels instant with no second GET. Same safety gates as the hover/focus warm: the `"false"` opt-out and the disabled skip apply identically, and an eager warm and a hover warm coalesce into a single GET (whichever runs second is a no-op). The pass is skipped when the browser signals Save-Data. Default behavior is unchanged — hover/focus warm remains the default. | `0.5.21-alpha` | 2026-07-19 |
+| ✅ | **Upload progress + drag-and-drop** — Extend the `data-gina-form-upload-*` staged client layer with transfer progress and drop-target support. **Progress shipped** (`0.5.24-alpha.2`): the staging POST reports real upload progress (`xhr.upload.onprogress`) through the registered `uploadProgress.<id>` client event, a `data-gina-form-upload-on-progress` window callback, and a declarative indicator (`data-gina-form-upload-progress`, default `<fieldId>-progress`) with a fully managed lifecycle. **Drag-and-drop shipped** (`0.5.24-alpha.2`): an attribute-marked dropzone (`data-gina-form-upload-dropzone="<elementId>"`, explicit id, opt-in) accepting dropped files through the exact same staging pipeline as the native file input — group tagging, previews, hidden metadata fields, reset/delete and upload progress included — with `idle`/`over`/`dropped` CSS state hooks, file-drags-only reaction, and first-file truncation on single-file inputs. Opt-in attributes, zero new dependencies, no server-contract change. | `0.5.24-alpha.2` | 2026-07-22 |
 
 ---
 

package/framework/v0.5.24/VERSION

@@ -0,0 +1 @@
+0.5.24