@fasl-work/caos-app-shell 0.19.9 → 0.19.10

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+## [0.19.010] - 2026-10-31
+
+### Fixed
+
+- `SurfacePage document` gives a documentation surface a full-column heading and lede, with one root-owned inset and the existing tabs and Focus controls. OreFlow's Introduction needed document framing without a nested page wrapper or product overrides (issue #167, SHD-088). Products adopt the optional `document` prop and remove their document-width workaround; ordinary surfaces retain their current layout.
+- Executive illustration checks measure transformed text bounds in the outer SVG viewBox and rendered font size through the complete text-to-screen matrix. Translated, scaled, rotated and nested labels are checked in their actual coordinate space; unavailable geometry fails explicitly. The existing bounds tolerance and 9 px font floor are unchanged (issue #167, SHG-076 to SHG-078).
+
 ## [0.19.009] - 2026-10-30
 
 ### Fixed

package/VERSION

@@ -1 +1 @@
-0.19.009
+0.19.010

package/dist/index.d.ts

@@ -888,6 +888,8 @@ interface CardDeckProps {
 declare function CardDeck({ cards, flip, carouselAbove, ariaLabel, className, lang: forced }: CardDeckProps): react.JSX.Element;
 
 interface SurfacePageProps {
+    /** Full-column document framing with the same tabs and Focus behavior. The root owns page padding. */
+    document?: boolean;
     /** The route's heading; omit it when the header's active route already names the surface. */
     title?: BiText;
     /** One line under the title: what the surface is for. */
@@ -925,7 +927,7 @@ interface SurfacePageProps {
  * `CaseWorkbench`'s, one piece of code (`useFocusMode`). The control sits at the end of the tab row (a slot beside the tab list) with
  * its space reserved, so it adds no row and moves nothing; it is hidden while the open view has no stage.
  */
-declare function SurfacePage({ title, lede, actions, tabs, value, onChange, deepLinkView, ariaLabel, instrument, focus, children }: SurfacePageProps): react.JSX.Element;
+declare function SurfacePage({ document: documentMode, title, lede, actions, tabs, value, onChange, deepLinkView, ariaLabel, instrument, focus, children }: SurfacePageProps): react.JSX.Element;
 
 /** Writes one query parameter with replaceState, keeping the router's history state (React Router keeps its entry
  * key and index there; replacing it with null broke the index the back button relies on). */

package/dist/index.js

@@ -3052,7 +3052,7 @@ function textOf(node) {
   return "";
 }
 var viewFocus = (tab) => !tab || !tab.focus ? null : tab.focus === true ? {} : tab.focus;
-function SurfacePage({ title, lede, actions, tabs, value, onChange, deepLinkView = true, ariaLabel, instrument, focus, children }) {
+function SurfacePage({ document: documentMode = false, title, lede, actions, tabs, value, onChange, deepLinkView = true, ariaLabel, instrument, focus, children }) {
   const lang = useShellLang();
   const placeAbove = useContext(PanelPathContext);
   const ids = (tabs ?? []).map((t2) => t2.id);
@@ -3110,11 +3110,11 @@ function SurfacePage({ title, lede, actions, tabs, value, onChange, deepLinkView
     ) });
   }
   const head = title !== void 0 || lede !== void 0 || actions !== void 0 && actions !== null;
-  const page = /* @__PURE__ */ jsxs("div", { className: "page-body wide caos-surface", "data-surface": "", "data-view-param": reserve ? viewParam ?? "" : void 0, children: [
+  const page = /* @__PURE__ */ jsxs("div", { className: `page-body wide caos-surface${documentMode ? " caos-surface-doc" : ""}`, "data-doc-page": documentMode ? "" : void 0, "data-surface": "", "data-view-param": reserve ? viewParam ?? "" : void 0, children: [
     head && /* @__PURE__ */ jsxs("div", { className: "caos-surface-head", children: [
       /* @__PURE__ */ jsxs("div", { className: "caos-surface-heading", children: [
         title !== void 0 && /* @__PURE__ */ jsx("h1", { className: "caos-surface-title", children: pick(title, lang) }),
-        lede !== void 0 && /* @__PURE__ */ jsx("p", { className: "caos-surface-lede", children: lede })
+        lede !== void 0 && /* @__PURE__ */ jsx("p", { className: `caos-surface-lede${documentMode ? " lede" : ""}`, children: lede })
       ] }),
       actions !== void 0 && actions !== null && /* @__PURE__ */ jsx("div", { className: "caos-surface-actions", children: actions })
     ] }),

package/gate/inpage.mjs

@@ -9,6 +9,55 @@ export function installLib() {
   G.raf = 0;
   // The smallest rendered size of an illustration label (EXEC_LIMITS.minLabelPx of gate/areas.mjs; test/executive.test.ts keeps them equal).
   const EXEC_MIN_LABEL_PX = 9;
+  /** Local text bounds mapped into the outer illustration's SVG user space, not screen pixels.
+   * All four corners matter for rotation/skew. Null is an explicit unmeasurable bound, never a pass.
+   * Screen matrices include nested viewports and root CSS transforms; the root inverse cancels them.
+   */
+  G.svgTextBounds = (root, text) => {
+    try {
+      const rootMatrix = root.getScreenCTM();
+      const textMatrix = text.getScreenCTM();
+      const valid = (m) => m && ['a', 'b', 'c', 'd', 'e', 'f'].every((k) => Number.isFinite(m[k]))
+        && m.a * m.d - m.b * m.c !== 0;
+      if (!valid(rootMatrix) || !valid(textMatrix)) return null;
+      const matrix = rootMatrix.inverse().multiply(textMatrix);
+      if (!valid(matrix)) return null;
+      const box = text.getBBox();
+      if (!['x', 'y', 'width', 'height'].every((k) => Number.isFinite(box[k]))) return null;
+      const corners = [[box.x, box.y], [box.x + box.width, box.y],
+        [box.x, box.y + box.height], [box.x + box.width, box.y + box.height]]
+        .map(([x, y]) => ({ x: matrix.a * x + matrix.c * y + matrix.e,
+          y: matrix.b * x + matrix.d * y + matrix.f }));
+      if (corners.some((p) => !Number.isFinite(p.x) || !Number.isFinite(p.y))) return null;
+      const x = Math.min(...corners.map((p) => p.x));
+      const y = Math.min(...corners.map((p) => p.y));
+      return { x, y, width: Math.max(...corners.map((p) => p.x)) - x,
+        height: Math.max(...corners.map((p) => p.y)) - y };
+    } catch {
+      return null;
+    }
+  };
+  /** Conservative rendered font size: the least stretch of the full text-to-screen mapping.
+   * Unlike a root bounding-rect ratio, singular values retain group/text/viewport scaling and
+   * ignore pure rotation. Normalize first, then use |det| / sigmaMax to avoid subtracting eigenvalues.
+   */
+  const svgTextFontPx = (text) => {
+    try {
+      const m = text.getScreenCTM();
+      const font = parseFloat(getComputedStyle(text).fontSize);
+      if (!m || m.is2D === false || !['a', 'b', 'c', 'd'].every((k) => Number.isFinite(m[k]))
+          || !Number.isFinite(font) || font <= 0) return null;
+      const norm = Math.max(Math.abs(m.a), Math.abs(m.b), Math.abs(m.c), Math.abs(m.d));
+      if (norm === 0) return null;
+      const a = m.a / norm, b = m.b / norm, c = m.c / norm, d = m.d / norm;
+      const largest = (Math.hypot(a + d, b - c) + Math.hypot(a - d, b + c)) / 2;
+      const scale = Math.abs(a * d - b * c) / largest * norm;
+      const px = font * scale;
+      return Number.isFinite(px) && px > 0 ? px : null;
+    } catch {
+      return null;
+    }
+  };
   G.counting = false;
   const nativeRaf = window.requestAnimationFrame ? window.requestAnimationFrame.bind(window) : null;
   if (nativeRaf) {
@@ -730,18 +779,18 @@ export function installLib() {
         if (!svg) return info;
         info.literal = literalsOf(svg);
         const vb = svg.viewBox && svg.viewBox.baseVal;
-        const w = svg.getBoundingClientRect().width;
-        const scale = vb && vb.width ? w / vb.width : 1;
         for (const t of svg.querySelectorAll('text')) {
           const label = (t.textContent || '').trim();
           if (!label || !visible(t)) continue;
           info.labels += 1;
           if (vb && vb.width) {
-            const b = t.getBBox();
-            if (b.x < vb.x - 1 || b.y < vb.y - 1 || b.x + b.width > vb.x + vb.width + 1 || b.y + b.height > vb.y + vb.height + 1) info.outside.push(label.slice(0, 40));
+            const b = G.svgTextBounds(svg, t);
+            if (!b) info.outside.push(`${label.slice(0, 40)} (bounds unavailable)`);
+            else if (b.x < vb.x - 1 || b.y < vb.y - 1 || b.x + b.width > vb.x + vb.width + 1 || b.y + b.height > vb.y + vb.height + 1) info.outside.push(label.slice(0, 40));
           }
-          const px = parseFloat(getComputedStyle(t).fontSize) * scale;
-          if (px < EXEC_MIN_LABEL_PX) info.small.push(`"${label.slice(0, 30)}" at ${px.toFixed(1)}px`);
+          const px = svgTextFontPx(t);
+          if (px === null) info.small.push(`"${label.slice(0, 30)}" (font scale unavailable)`);
+          else if (px < EXEC_MIN_LABEL_PX) info.small.push(`"${label.slice(0, 30)}" at ${px.toFixed(1)}px`);
         }
         return info;
       });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fasl-work/caos-app-shell",
-  "version": "0.19.9",
+  "version": "0.19.10",
   "description": "Shared web-app shell, workbench primitives, content primitives, design system and measured gate for the CAOS / Faena public apps (ADR-0016, ADR-0017, ADR-0071).",
   "license": "MIT",
   "author": "Felipe Santibáñez-Leal",

package/reserved-classes.json

@@ -167,6 +167,7 @@
     "caos-surface",
     "caos-surface-actions",
     "caos-surface-body",
+    "caos-surface-doc",
     "caos-surface-focus",
     "caos-surface-head",
     "caos-surface-heading",
@@ -494,6 +495,7 @@
     "caos-surface",
     "caos-surface-actions",
     "caos-surface-body",
+    "caos-surface-doc",
     "caos-surface-focus",
     "caos-surface-head",
     "caos-surface-heading",

package/styles.css

@@ -252,6 +252,9 @@ code, kbd { font-family: var(--font-mono); }
 .caos-surface-title { margin: 0; font-size: var(--text-xl); }
 .caos-surface-actions { display: inline-flex; flex-wrap: wrap; align-items: center; gap: var(--space-2); }
 .caos-surface-lede { margin: 0; color: var(--color-fg-subtle); font-size: var(--text-md); max-width: var(--measure-text); }
+/* Document surfaces own their one page inset; actions cannot shrink the title/lede column. */
+.caos-surface-doc > .caos-surface-head > .caos-surface-heading { flex: 1 1 100%; width: 100%; }
+.caos-surface-doc .caos-surface-lede { max-width: none; font-size: var(--text-md); }
 .caos-surface-body { flex: 1 1 auto; min-height: 0; min-width: 0; display: flex; flex-direction: column; }
 .caos-surface-body > .tabs { flex: 1 1 auto; min-height: 0; display: flex; flex-direction: column; }
 .caos-surface-body > .tabs > .tabpanel:not([hidden]) { flex: 1 1 auto; min-height: 0; overflow: auto; display: flex; flex-direction: column; gap: 0.6rem; }