@wildo-ai/framework-knowledge 1.1.0 → 1.1.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (240) hide show
  1. package/dist/esm/framework-knowledge.definitions.d.ts +1 -1
  2. package/dist/esm/framework-knowledge.definitions.d.ts.map +1 -1
  3. package/dist/esm/framework-knowledge.definitions.js +43 -2
  4. package/dist/esm/framework-knowledge.definitions.js.map +1 -1
  5. package/dist/esm/framework-knowledge.loader.d.ts +19 -0
  6. package/dist/esm/framework-knowledge.loader.d.ts.map +1 -1
  7. package/dist/esm/framework-knowledge.loader.js +32 -0
  8. package/dist/esm/framework-knowledge.loader.js.map +1 -1
  9. package/dist/esm/framework-knowledge.schemas.d.ts +12 -0
  10. package/dist/esm/framework-knowledge.schemas.d.ts.map +1 -1
  11. package/dist/esm/framework-knowledge.schemas.js.map +1 -1
  12. package/dist/esm/playbooks/bottom_up.assemble-verify/playbook.definition.d.ts +46 -0
  13. package/dist/esm/playbooks/bottom_up.assemble-verify/playbook.definition.d.ts.map +1 -0
  14. package/dist/esm/playbooks/bottom_up.assemble-verify/playbook.definition.js +55 -0
  15. package/dist/esm/playbooks/bottom_up.assemble-verify/playbook.definition.js.map +1 -0
  16. package/dist/esm/playbooks/bottom_up.build-decompose/playbook.definition.d.ts +4 -4
  17. package/dist/esm/playbooks/bottom_up.build-decompose/playbook.definition.js +3 -3
  18. package/dist/esm/playbooks/bottom_up.build-decompose/playbook.definition.js.map +1 -1
  19. package/dist/esm/playbooks/bottom_up.build-dispatch/playbook.definition.d.ts +0 -3
  20. package/dist/esm/playbooks/bottom_up.build-dispatch/playbook.definition.d.ts.map +1 -1
  21. package/dist/esm/playbooks/bottom_up.build-dispatch/playbook.definition.js +0 -1
  22. package/dist/esm/playbooks/bottom_up.build-dispatch/playbook.definition.js.map +1 -1
  23. package/dist/esm/playbooks/bottom_up.build-scale/playbook.definition.d.ts +0 -3
  24. package/dist/esm/playbooks/bottom_up.build-scale/playbook.definition.d.ts.map +1 -1
  25. package/dist/esm/playbooks/bottom_up.build-scale/playbook.definition.js +0 -1
  26. package/dist/esm/playbooks/bottom_up.build-scale/playbook.definition.js.map +1 -1
  27. package/dist/esm/playbooks/bottom_up.domain-plan/playbook.definition.d.ts +2 -7
  28. package/dist/esm/playbooks/bottom_up.domain-plan/playbook.definition.d.ts.map +1 -1
  29. package/dist/esm/playbooks/bottom_up.domain-plan/playbook.definition.js +0 -1
  30. package/dist/esm/playbooks/bottom_up.domain-plan/playbook.definition.js.map +1 -1
  31. package/dist/esm/playbooks/bottom_up.foundation/playbook.definition.d.ts +8 -3
  32. package/dist/esm/playbooks/bottom_up.foundation/playbook.definition.d.ts.map +1 -1
  33. package/dist/esm/playbooks/bottom_up.foundation/playbook.definition.js +22 -1
  34. package/dist/esm/playbooks/bottom_up.foundation/playbook.definition.js.map +1 -1
  35. package/dist/esm/playbooks/bottom_up.placement-plan/playbook.definition.d.ts +0 -3
  36. package/dist/esm/playbooks/bottom_up.placement-plan/playbook.definition.d.ts.map +1 -1
  37. package/dist/esm/playbooks/bottom_up.placement-plan/playbook.definition.js +0 -1
  38. package/dist/esm/playbooks/bottom_up.placement-plan/playbook.definition.js.map +1 -1
  39. package/dist/esm/playbooks/refinement.compliance-document-candidate/playbook.definition.d.ts +4 -1
  40. package/dist/esm/playbooks/refinement.compliance-document-candidate/playbook.definition.d.ts.map +1 -1
  41. package/dist/esm/playbooks/refinement.compliance-document-candidate/playbook.definition.js +4 -1
  42. package/dist/esm/playbooks/refinement.compliance-document-candidate/playbook.definition.js.map +1 -1
  43. package/dist/esm/playbooks/refinement.document-facts/playbook.definition.d.ts +1 -1
  44. package/dist/esm/playbooks/refinement.document-facts/playbook.definition.js +13 -13
  45. package/dist/esm/playbooks/refinement.document-facts/playbook.definition.js.map +1 -1
  46. package/dist/esm/playbooks/top_down.brand-identity/playbook.definition.d.ts +3 -4
  47. package/dist/esm/playbooks/top_down.brand-identity/playbook.definition.d.ts.map +1 -1
  48. package/dist/esm/playbooks/top_down.brand-identity/playbook.definition.js +3 -3
  49. package/dist/esm/playbooks/top_down.brand-identity/playbook.definition.js.map +1 -1
  50. package/dist/esm/playbooks/top_down.business-model/playbook.definition.d.ts +2 -7
  51. package/dist/esm/playbooks/top_down.business-model/playbook.definition.d.ts.map +1 -1
  52. package/dist/esm/playbooks/top_down.business-model/playbook.definition.js +0 -1
  53. package/dist/esm/playbooks/top_down.business-model/playbook.definition.js.map +1 -1
  54. package/dist/esm/playbooks/top_down.capability-map/playbook.definition.d.ts +2 -7
  55. package/dist/esm/playbooks/top_down.capability-map/playbook.definition.d.ts.map +1 -1
  56. package/dist/esm/playbooks/top_down.capability-map/playbook.definition.js +0 -1
  57. package/dist/esm/playbooks/top_down.capability-map/playbook.definition.js.map +1 -1
  58. package/dist/esm/playbooks/top_down.compliance-analysis/playbook.definition.d.ts +54 -0
  59. package/dist/esm/playbooks/top_down.compliance-analysis/playbook.definition.d.ts.map +1 -0
  60. package/dist/esm/playbooks/top_down.compliance-analysis/playbook.definition.js +127 -0
  61. package/dist/esm/playbooks/top_down.compliance-analysis/playbook.definition.js.map +1 -0
  62. package/dist/esm/playbooks/top_down.compliance-conception/playbook.definition.d.ts +76 -0
  63. package/dist/esm/playbooks/top_down.compliance-conception/playbook.definition.d.ts.map +1 -0
  64. package/dist/esm/playbooks/top_down.compliance-conception/playbook.definition.js +92 -0
  65. package/dist/esm/playbooks/top_down.compliance-conception/playbook.definition.js.map +1 -0
  66. package/dist/esm/playbooks/top_down.compliance-evidence-adequacy/playbook.definition.d.ts +30 -0
  67. package/dist/esm/playbooks/top_down.compliance-evidence-adequacy/playbook.definition.d.ts.map +1 -0
  68. package/dist/esm/playbooks/top_down.compliance-evidence-adequacy/playbook.definition.js +29 -0
  69. package/dist/esm/playbooks/top_down.compliance-evidence-adequacy/playbook.definition.js.map +1 -0
  70. package/dist/esm/playbooks/top_down.compliance-posture/playbook.definition.d.ts +9 -44
  71. package/dist/esm/playbooks/top_down.compliance-posture/playbook.definition.d.ts.map +1 -1
  72. package/dist/esm/playbooks/top_down.compliance-posture/playbook.definition.js +4 -53
  73. package/dist/esm/playbooks/top_down.compliance-posture/playbook.definition.js.map +1 -1
  74. package/dist/esm/playbooks/top_down.compliance-research/playbook.definition.d.ts +31 -0
  75. package/dist/esm/playbooks/top_down.compliance-research/playbook.definition.d.ts.map +1 -0
  76. package/dist/esm/playbooks/top_down.compliance-research/playbook.definition.js +26 -0
  77. package/dist/esm/playbooks/top_down.compliance-research/playbook.definition.js.map +1 -0
  78. package/dist/esm/playbooks/top_down.market-analysis/playbook.definition.d.ts +2 -7
  79. package/dist/esm/playbooks/top_down.market-analysis/playbook.definition.d.ts.map +1 -1
  80. package/dist/esm/playbooks/top_down.market-analysis/playbook.definition.js +0 -1
  81. package/dist/esm/playbooks/top_down.market-analysis/playbook.definition.js.map +1 -1
  82. package/dist/esm/playbooks/top_down.market-snapshot-produce/playbook.definition.d.ts +0 -8
  83. package/dist/esm/playbooks/top_down.market-snapshot-produce/playbook.definition.d.ts.map +1 -1
  84. package/dist/esm/playbooks/top_down.market-snapshot-produce/playbook.definition.js +0 -1
  85. package/dist/esm/playbooks/top_down.market-snapshot-produce/playbook.definition.js.map +1 -1
  86. package/dist/esm/playbooks/top_down.phase-gate/playbook.definition.d.ts +2 -7
  87. package/dist/esm/playbooks/top_down.phase-gate/playbook.definition.d.ts.map +1 -1
  88. package/dist/esm/playbooks/top_down.phase-gate/playbook.definition.js +0 -1
  89. package/dist/esm/playbooks/top_down.phase-gate/playbook.definition.js.map +1 -1
  90. package/dist/esm/playbooks/top_down.requirements-definition/playbook.definition.d.ts +2 -7
  91. package/dist/esm/playbooks/top_down.requirements-definition/playbook.definition.d.ts.map +1 -1
  92. package/dist/esm/playbooks/top_down.requirements-definition/playbook.definition.js +0 -1
  93. package/dist/esm/playbooks/top_down.requirements-definition/playbook.definition.js.map +1 -1
  94. package/dist/esm/playbooks/top_down.scope-roadmap/playbook.definition.d.ts +2 -7
  95. package/dist/esm/playbooks/top_down.scope-roadmap/playbook.definition.d.ts.map +1 -1
  96. package/dist/esm/playbooks/top_down.scope-roadmap/playbook.definition.js +5 -3
  97. package/dist/esm/playbooks/top_down.scope-roadmap/playbook.definition.js.map +1 -1
  98. package/dist/esm/playbooks/top_down.value-proposition/playbook.definition.d.ts +0 -3
  99. package/dist/esm/playbooks/top_down.value-proposition/playbook.definition.d.ts.map +1 -1
  100. package/dist/esm/playbooks/top_down.value-proposition/playbook.definition.js +0 -1
  101. package/dist/esm/playbooks/top_down.value-proposition/playbook.definition.js.map +1 -1
  102. package/dist/esm/playbooks/top_down.vision-elicitation/playbook.definition.d.ts +4 -5
  103. package/dist/esm/playbooks/top_down.vision-elicitation/playbook.definition.d.ts.map +1 -1
  104. package/dist/esm/playbooks/top_down.vision-elicitation/playbook.definition.js +25 -4
  105. package/dist/esm/playbooks/top_down.vision-elicitation/playbook.definition.js.map +1 -1
  106. package/dist/knowledge/assurance-authority-bases/wildo-safe-baseline-v1/authority-basis.json +1 -1
  107. package/dist/knowledge/assurance-authority-bases/wildo-safe-baseline-v1/external-framework-mapping.json +1 -0
  108. package/dist/knowledge/manifest.json +8 -8
  109. package/dist/knowledge/playbooks/bottom_up.assemble-verify/method.md +51 -0
  110. package/dist/knowledge/playbooks/bottom_up.assemble-verify/playbook.json +43 -0
  111. package/dist/knowledge/playbooks/bottom_up.build-decompose/method.md +27 -10
  112. package/dist/knowledge/playbooks/bottom_up.build-decompose/playbook.json +8 -7
  113. package/dist/knowledge/playbooks/bottom_up.build-dispatch/method.md +6 -4
  114. package/dist/knowledge/playbooks/bottom_up.build-dispatch/playbook.json +4 -6
  115. package/dist/knowledge/playbooks/bottom_up.build-scale/method.md +5 -4
  116. package/dist/knowledge/playbooks/bottom_up.build-scale/playbook.json +4 -6
  117. package/dist/knowledge/playbooks/bottom_up.domain-plan/method.md +0 -4
  118. package/dist/knowledge/playbooks/bottom_up.domain-plan/playbook.json +4 -6
  119. package/dist/knowledge/playbooks/bottom_up.foundation/method.md +49 -22
  120. package/dist/knowledge/playbooks/bottom_up.foundation/playbook.json +14 -6
  121. package/dist/knowledge/playbooks/bottom_up.placement-plan/playbook.json +2 -4
  122. package/dist/knowledge/playbooks/refinement.compliance-document-candidate/method.md +46 -1
  123. package/dist/knowledge/playbooks/refinement.compliance-document-candidate/playbook.json +7 -3
  124. package/dist/knowledge/playbooks/refinement.document-facts/method.md +18 -4
  125. package/dist/knowledge/playbooks/refinement.document-facts/playbook.json +4 -2
  126. package/dist/knowledge/playbooks/top_down.brand-identity/method.md +2 -3
  127. package/dist/knowledge/playbooks/top_down.brand-identity/playbook.json +8 -7
  128. package/dist/knowledge/playbooks/top_down.business-model/playbook.json +3 -5
  129. package/dist/knowledge/playbooks/top_down.capability-map/method.md +0 -2
  130. package/dist/knowledge/playbooks/top_down.capability-map/playbook.json +4 -6
  131. package/dist/knowledge/playbooks/top_down.compliance-analysis/method.md +41 -0
  132. package/dist/knowledge/playbooks/top_down.compliance-analysis/playbook.json +100 -0
  133. package/dist/knowledge/playbooks/top_down.compliance-conception/method.md +117 -0
  134. package/dist/knowledge/playbooks/top_down.compliance-conception/playbook.json +86 -0
  135. package/dist/knowledge/playbooks/top_down.compliance-evidence-adequacy/method.md +61 -0
  136. package/dist/knowledge/playbooks/top_down.compliance-evidence-adequacy/playbook.json +41 -0
  137. package/dist/knowledge/playbooks/top_down.compliance-posture/method.md +21 -4
  138. package/dist/knowledge/playbooks/top_down.compliance-posture/playbook.json +14 -57
  139. package/dist/knowledge/playbooks/top_down.compliance-research/method.md +76 -0
  140. package/dist/knowledge/playbooks/top_down.compliance-research/playbook.json +42 -0
  141. package/dist/knowledge/playbooks/top_down.market-analysis/playbook.json +3 -5
  142. package/dist/knowledge/playbooks/top_down.market-evidence-adequacy/playbook.json +3 -1
  143. package/dist/knowledge/playbooks/top_down.market-research/playbook.json +3 -1
  144. package/dist/knowledge/playbooks/top_down.market-snapshot-produce/playbook.json +3 -5
  145. package/dist/knowledge/playbooks/top_down.phase-gate/method.md +8 -4
  146. package/dist/knowledge/playbooks/top_down.phase-gate/playbook.json +4 -6
  147. package/dist/knowledge/playbooks/top_down.requirements-definition/method.md +9 -7
  148. package/dist/knowledge/playbooks/top_down.requirements-definition/playbook.json +4 -6
  149. package/dist/knowledge/playbooks/top_down.scope-roadmap/method.md +2 -2
  150. package/dist/knowledge/playbooks/top_down.scope-roadmap/playbook.json +8 -7
  151. package/dist/knowledge/playbooks/top_down.value-proposition/method.md +0 -2
  152. package/dist/knowledge/playbooks/top_down.value-proposition/playbook.json +4 -6
  153. package/dist/knowledge/playbooks/top_down.vision-elicitation/method.md +2 -2
  154. package/dist/knowledge/playbooks/top_down.vision-elicitation/playbook.json +8 -7
  155. package/dist/knowledge/references/companion.technical-doc.service.md +102 -2
  156. package/dist/knowledge/references/example.config.app-shell.full.md +0 -1
  157. package/dist/knowledge/references/example.module.companion-exports.full.md +1 -0
  158. package/dist/knowledge/references/platform.config.saas.md +1 -0
  159. package/dist/knowledge/references/presets.models.surface-policy.md +19 -10
  160. package/dist/knowledge/references/saas.frontend.app-level-component.configuration.md +25 -1
  161. package/dist/knowledge/references/saas.frontend.composite-view.authoring.md +45 -0
  162. package/dist/knowledge/references/saas.frontend.display-layout.reading-measure.md +34 -0
  163. package/dist/knowledge/references/saas.frontend.navigation.operation-override.md +45 -0
  164. package/dist/knowledge/references/saas.frontend.public-shell.identity-mode.md +65 -0
  165. package/dist/knowledge/references/saas.frontend.resource-operation-frontend-config.md +89 -0
  166. package/dist/knowledge/references/saas.models.data-mode-read-list.md +31 -4
  167. package/dist/knowledge/references/saas.models.engine-capabilities.md +26 -6
  168. package/dist/knowledge/references/saas.models.file-upload-grant.md +179 -0
  169. package/dist/knowledge/references/saas.models.navigation.surface-vocabulary.md +124 -0
  170. package/dist/knowledge/references/saas.models.navigation.transition-vocabulary.md +99 -0
  171. package/dist/knowledge/references/saas.models.navigation.zone-declaration.md +127 -0
  172. package/dist/knowledge/references/saas.models.provider-capabilities.md +4 -3
  173. package/dist/knowledge/references/saas.models.resource-config.operation-variant-client-timeout.md +42 -0
  174. package/dist/knowledge/references/saas.specifications.application-authored-document-fact-specification.contract.md +29 -0
  175. package/dist/knowledge/references/saas.specifications.application-document-fact-specification.contract.md +11 -31
  176. package/dist/knowledge/references/saas.specifications.assurance-document-blueprint.contract.md +32 -2
  177. package/dist/knowledge/references/saas.specifications.assurance-program.contract.md +29 -6
  178. package/dist/knowledge/references/saas.specifications.companion-exports.contract.md +20 -0
  179. package/dist/knowledge/references/saas.specifications.resource-spec-config.md +22 -0
  180. package/dist/knowledge/references/zod.decorators.display-edit-modes.md +6 -0
  181. package/dist/knowledge/references/zod.decorators.field-spec-params.md +31 -5
  182. package/dist/knowledge/references/zod.decorators.per-primitive-ui.md +43 -0
  183. package/dist/knowledge/references/zod.decorators.primitive-ui.md +3 -0
  184. package/dist/knowledge/references/zod.decorators.shared-structural-params.md +15 -0
  185. package/dist/knowledge/registries/assurance-authority-bases.json +3 -2
  186. package/dist/knowledge/registries/framework-topics.json +99 -1
  187. package/dist/knowledge/registries/playbooks.json +81 -8
  188. package/dist/knowledge/registries/source-tags.json +757 -588
  189. package/dist/knowledge/skills/INDEX.md +3 -3
  190. package/dist/knowledge/skills/brand-logo-authoring/SKILL.md +2 -1
  191. package/dist/knowledge/skills/compliance-document-authoring/references/document-composition-governance.md +5 -1
  192. package/dist/knowledge/skills/compliance-document-authoring/references/framework-application-document-fact-specification-contract.md +66 -37
  193. package/dist/knowledge/skills/compliance-document-authoring/references/framework-assurance-document-blueprint-contract.md +40 -7
  194. package/dist/knowledge/skills/config-app-shell/SKILL.md +25 -1
  195. package/dist/knowledge/skills/config-app-shell/references/framework-app-shell-api.md +25 -1
  196. package/dist/knowledge/skills/config-app-shell/references/framework-public-shell-identity-api.md +124 -0
  197. package/dist/knowledge/skills/config-design-system/SKILL.md +23 -1
  198. package/dist/knowledge/skills/config-design-system/references/framework-surface-policy-api.md +19 -10
  199. package/dist/knowledge/skills/config-design-system/references/loading-placeholder-authoring.md +47 -0
  200. package/dist/knowledge/skills/config-navigation/SKILL.md +75 -2
  201. package/dist/knowledge/skills/config-navigation/references/framework-content-width-api.md +98 -0
  202. package/dist/knowledge/skills/config-navigation/references/framework-navigation-operation-override-api.md +54 -0
  203. package/dist/knowledge/skills/config-navigation/references/framework-navigation-vocabulary-api.md +232 -0
  204. package/dist/knowledge/skills/config-navigation/references/framework-navigation-zone-declaration-api.md +149 -0
  205. package/dist/knowledge/skills/config-navigation/references/how-navigation-resolves.md +114 -0
  206. package/dist/knowledge/skills/config-navigation/references/navigation-configuration-map.md +133 -0
  207. package/dist/knowledge/skills/config-saas/SKILL.md +19 -2
  208. package/dist/knowledge/skills/config-saas/references/compliance-declarations.md +111 -0
  209. package/dist/knowledge/skills/config-saas/references/framework-provider-capabilities-api.md +30 -9
  210. package/dist/knowledge/skills/config-saas/references/framework-wildo-saas-config-api.md +1 -0
  211. package/dist/knowledge/skills/flows-actors-a2a-exposure/SKILL.md +2 -1
  212. package/dist/knowledge/skills/flows-actors-a2a-exposure/references/framework-flows-actors-a2a-contract.md +4 -3
  213. package/dist/knowledge/skills/market-companion-prompt-enrichment/SKILL.md +20 -0
  214. package/dist/knowledge/skills/market-companion-prompt-enrichment/references/framework-companion-behavior-api.md +20 -0
  215. package/dist/knowledge/skills/module-companion-exports/SKILL.md +1 -0
  216. package/dist/knowledge/skills/module-companion-exports/references/companion-exports-by-package.md +20 -0
  217. package/dist/knowledge/skills/resource-add-field/SKILL.md +3 -3
  218. package/dist/knowledge/skills/resource-add-field/references/framework-field-cross-layer-api.md +104 -0
  219. package/dist/knowledge/skills/resource-config-wiring/SKILL.md +13 -0
  220. package/dist/knowledge/skills/resource-config-wiring/references/framework-saas-models-resource-config-api.md +71 -4
  221. package/dist/knowledge/skills/resource-custom-view/references/custom-view-contracts.md +89 -0
  222. package/dist/knowledge/skills/resource-mcp-tool-exposure/SKILL.md +22 -1
  223. package/dist/knowledge/skills/resource-mcp-tool-exposure/references/framework-file-upload-grant-contract.md +192 -0
  224. package/dist/knowledge/skills/resource-rag-source-fields/references/framework-embeddings-capability-api.md +28 -8
  225. package/dist/knowledge/skills/resource-schema-authoring/references/framework-shared-structural-params-api.md +15 -0
  226. package/dist/knowledge/skills/resource-ui-behavior/references/framework-display-edit-modes-api.md +6 -0
  227. package/dist/knowledge/skills/resource-ui-behavior/references/framework-frontend-resource-ui-contracts-api.md +89 -0
  228. package/dist/knowledge/skills/resource-ui-behavior/references/framework-per-primitive-ui-api.md +43 -0
  229. package/dist/knowledge/skills/resource-ui-behavior/references/framework-primitive-ui-api.md +3 -0
  230. package/dist/knowledge/skills/settings-placement-authoring/SKILL.md +1 -1
  231. package/dist/knowledge/skills/spec-companion-exports/SKILL.md +1 -0
  232. package/dist/knowledge/skills/spec-companion-exports/references/framework-companion-exports-contract-api.md +20 -0
  233. package/dist/knowledge/skills/spec-resource-update/references/framework-field-spec-params-api.md +31 -5
  234. package/dist/knowledge/skills/spec-resource-update/references/framework-spec-resource-contracts-api.md +22 -0
  235. package/dist/knowledge/skills/views-composite-authoring/references/framework-composite-view-contracts-api.md +45 -0
  236. package/dist/knowledge/topic-index.json +504 -156
  237. package/dist/tsconfig.build.tsbuildinfo +1 -1
  238. package/dist/tsconfig.tsbuildinfo +1 -1
  239. package/package.json +4 -4
  240. package/dist/esm/.builder.pid +0 -9
@@ -371,6 +371,26 @@ export const CardActionPlacementSchema = z.object({
371
371
  /** Authored 2-axis card action placement — inferred from {@link CardActionPlacementSchema}. */
372
372
  export type CardActionPlacement = z.infer<typeof CardActionPlacementSchema>;
373
373
 
374
+ /**
375
+ * Who paints the identity GLYPH on this operation's page header.
376
+ *
377
+ * The header band renders the resource's registry icon beside the identity line by default. A
378
+ * `layout.header` template that composes its own record-linked glyph (a per-row kind icon, a
379
+ * per-family symbol) would otherwise sit BESIDE the resource icon — two glyphs naming one thing.
380
+ *
381
+ * Declared at the OPERATION layer rather than detected from the template, deliberately: the
382
+ * resource icon renders before the template mounts, so detection could only suppress it after the
383
+ * fact — a glyph that flashes and vanishes on every load. Mirrors
384
+ * `SummaryTitlePlacement.TEMPLATE_OWNED`, the same contract one surface over: ceding a
385
+ * framework-owned element to the template is a declaration, not an inference.
386
+ */
387
+ export enum HeaderIconPlacement {
388
+ /** The framework renders the resource's registry icon (default). */
389
+ AUTO = 'auto',
390
+ /** The header template owns the glyph; the framework renders none. */
391
+ TEMPLATE_OWNED = 'template_owned',
392
+ }
393
+
374
394
  export const ResourceOperationFrontendConfigSchema = z.object({
375
395
  /**
376
396
  * The operation's frontend **surface** — see {@link ResourceOperationFrontendSurface}.
@@ -382,6 +402,8 @@ export const ResourceOperationFrontendConfigSchema = z.object({
382
402
  * Replaces the former `isAddressable` boolean — read via `isOperationAddressable()`.
383
403
  */
384
404
  surface: z.enum(ResourceOperationFrontendSurface),
405
+ /** Who paints the page header's identity glyph — see {@link HeaderIconPlacement}. Omitted = AUTO. */
406
+ headerIconPlacement: z.enum(HeaderIconPlacement).optional(),
385
407
  /**
386
408
  * How this operation's action is surfaced — see {@link ActionVisibility}. Omitted
387
409
  * (the common case) behaves as `ALWAYS`.
@@ -461,6 +483,30 @@ export const ResourceOperationFrontendConfigSchema = z.object({
461
483
  * without a date heading rather than being dropped.
462
484
  */
463
485
  temporalGroupField: z.string().optional(),
486
+ /**
487
+ * Group CARDS-mode rows into buckets by this ENUM field, rendering the
488
+ * enum value's own label as a heading between groups.
489
+ *
490
+ * Sibling of {@link temporalGroupField}, and deliberately NOT the same
491
+ * algorithm. Temporal grouping ADJACENT-MERGES in server order, because
492
+ * dates are open-ended and a page can legitimately revisit one. An enum is
493
+ * a CLOSED, ORDERED vocabulary, so its buckets are emitted in the enum's
494
+ * DECLARATION ORDER regardless of the order rows arrived in — the
495
+ * declaration is the authority for "which concern comes first", and a
496
+ * server sort cannot express it without a second, drifting copy of that
497
+ * order. Rows are therefore collected across the whole fetched page rather
498
+ * than merged adjacently, and no sort needs pairing with it.
499
+ *
500
+ * Headings resolve through `tResourceFieldEnumValue` — the SAME source the
501
+ * filters panel and the promoted quick-filter tabs use, so a bucket
502
+ * heading and its tab can never disagree.
503
+ *
504
+ * Ignored in TABLE mode (column sorting owns the ordering there). Rows
505
+ * whose value is absent, or outside the vocabulary, render in a trailing
506
+ * bucket with no heading rather than being dropped — the same fail-open
507
+ * the temporal grouping makes.
508
+ */
509
+ enumGroupField: z.string().optional(),
464
510
  /**
465
511
  * CARDS-mode arrangement — a single-column bordered LIST (default) or an
466
512
  * N-column responsive GRID. See {@link CardLayoutStyle}. `columns` (1–6) is
@@ -514,6 +560,49 @@ export const ResourceOperationFrontendConfigSchema = z.object({
514
560
  * into a description via the `.describe()` decorator.
515
561
  */
516
562
  hasDescription: z.boolean().optional(),
563
+ /**
564
+ * What happens to an ADJACENT zone (secondary / companion) this operation
565
+ * splits into, once that zone's last content is dismissed — overriding the
566
+ * zone's own `onEmpty` while this operation occupies primary.
567
+ *
568
+ * The zone-level `ZoneConfig.onEmpty` is one value for every destination that
569
+ * splits into that zone, and destinations legitimately disagree: a LIST wants
570
+ * the detail pane to stay put (`EMPTY_STATE`) so the layout does not reflow
571
+ * while a reviewer steps through rows, while a CANVAS wants its width back
572
+ * (`COLLAPSE`) the moment nothing is selected. Both share one secondary zone,
573
+ * so without this override one of them is always wrong.
574
+ *
575
+ * Declared on the SOURCE operation — the one occupying primary — not on the
576
+ * operation that lands in the pane: it answers "what should MY layout do when
577
+ * the detail closes", which is a property of the surface being returned to.
578
+ *
579
+ * Omitted (the common case) defers to the zone, which itself defaults to
580
+ * `ZoneEmptyBehavior.COLLAPSE`. Resolution order is destination → zone →
581
+ * COLLAPSE; see `resolveZoneEmptyBehavior`.
582
+ */
583
+ adjacentZoneOnEmpty: z.enum(ZoneEmptyBehavior).optional(),
584
+ /**
585
+ * How wide this destination's content may grow in the zone, in the framework's shared width
586
+ * vocabulary — the SAME `ResponsiveMaxWidth` a Surface, a `DisplayLayout` and a `FormLayout` use.
587
+ *
588
+ * Omitted (the common case) is `'content'`: capped and centred at `var(--content-max-width, 80rem)`,
589
+ * right for a form, a list or a detail page and wrong only for content whose value IS the space it
590
+ * occupies — a board, a wide table, a canvas — which declare `'none'`.
591
+ */
592
+ zoneContentMaxWidth: z.enum(RESPONSIVE_MAX_WIDTH_VALUES).optional(),
593
+ /**
594
+ * Whether this destination's content fills the zone's HEIGHT as well.
595
+ *
596
+ * `true` makes the zone's content boundary a definite-height flex column, so this view's root may use
597
+ * `flex-1 min-h-0` and resolve against something real. Without it a canvas has no intrinsic height
598
+ * and collapses to zero — which is why one had to hand-roll `h-[70vh]`, sizing against the WINDOW
599
+ * rather than the container it sits in. PRIMARY only: an adjacent zone scrolls, so a filling child
600
+ * and a scrolling parent contradict each other.
601
+ *
602
+ * Separate from the width above ON PURPOSE — see `zone-content-geometry.ts` for why the enum that
603
+ * fused them could not express a capped width with a definite height.
604
+ */
605
+ zoneContentFillsHeight: z.boolean().optional(),
517
606
  });
518
607
 
519
608
  /**
@@ -71,6 +71,28 @@ export enum IntrospectionTenancyStance {
71
71
  */
72
72
  APPLICATION_STRUCTURE = 'application-structure',
73
73
 
74
+ /**
75
+ * The rows are the DEVELOPMENT COMPANION'S OWN RUNTIME PROJECTIONS for the one application it
76
+ * serves — the playbook eligibility board, the build plan, the run write-register, the execution
77
+ * traces. Like `APPLICATION_STRUCTURE` they carry no tenant dimension and no scope predicate can
78
+ * apply; UNLIKE it, they are not derived from the application's source, and the tenancy stance is
79
+ * where that difference must stay visible (added 2026-09-01, creation-board resources plan):
80
+ *
81
+ * - `APPLICATION_STRUCTURE`'s public-read posture (`APP_PUBLIC` variants on the workbench's
82
+ * structural projections) rests on the rows being the application's OWN source, which anyone
83
+ * with the working tree can already read. That argument does NOT extend to runtime state, so a
84
+ * resource declaring this stance is expected to gate its variants on an authenticated role —
85
+ * never `APP_PUBLIC`.
86
+ * - Row-level tenant-anchor checks are bypassed for this stance exactly as for
87
+ * `APPLICATION_STRUCTURE` (the rows carry no anchor BY CONTRACT); authorization comes from the
88
+ * session and the operation's role gate.
89
+ *
90
+ * Fusing this into `APPLICATION_STRUCTURE` was rejected for the enum's own founding reason: an
91
+ * unstated distinction is indistinguishable from an overlooked one, and the next decision site
92
+ * keyed off the stance would inherit a claim nobody checked.
93
+ */
94
+ APPLICATION_RUNTIME = 'application-runtime',
95
+
74
96
  /**
75
97
  * The rows carry a tenant dimension and a scope predicate must be pushed into the source.
76
98
  *
@@ -167,10 +189,15 @@ export enum PersistenceAdapter {
167
189
  * "how rows are reached", and the mechanism behind it is a binding an author declares.
168
190
  *
169
191
  * Distinct from `HTTP_API`, deliberately, and not merely because the transport differs. Retrieval
170
- * is a SUBPROCESS that imports the target application's built modules; it costs seconds rather than
171
- * milliseconds, it requires that application's `dist` to exist, and its failure mode is a behavior
172
- * throwing rather than a row being absent. Collapsing the two would give one declaration whose
173
- * discriminator chooses between an HTTP call and a subprocess — two adapters wearing one name.
192
+ * is the COMPANION's decision per behavior (amended 2026-09-01): the app-import behaviors run a
193
+ * SUBPROCESS that imports the target application's built modules — seconds per read, requiring
194
+ * that application's `dist`, failing as a thrown behavior — while the creation-plane behaviors
195
+ * are IN-PROCESS projections of the companion's own runtime services (playbook eligibility,
196
+ * build plan, write register, traces). Both reach the engine through the same
197
+ * `IntrospectionResourceSourceBackendPort`; the adapter never encodes the mechanism, which is
198
+ * exactly why a behavior id is an engine-opaque string. Collapsing this into `HTTP_API` would
199
+ * still be wrong for the original reason: its failure mode is a source throwing rather than a
200
+ * row being absent, and nothing here is reached over a network API.
174
201
  *
175
202
  * ## What every adapter decision site must honor
176
203
  *
@@ -55,11 +55,13 @@ export enum EngineCapability {
55
55
  * extraction into `AI_LLM` would have made one `selection[AI_LLM].primary` decide all three,
56
56
  * which is exactly the defect that split `AI_EMBEDDINGS` out of `AI_LLM`.
57
57
  *
58
- * ## Not to be confused with `DOCUMENT_GENERATION`
58
+ * ## Not to be confused with PDF GENERATION
59
59
  *
60
- * `DOCUMENT_GENERATION` is PDF *generation* — templates and data become bytes. This is the
61
- * opposite direction: bytes become text. The names are adjacent and the capabilities are
62
- * unrelated; nothing routes between them.
60
+ * PDF generation — templates and data become bytes — is the `pdfTemplates` surface, done
61
+ * in-process and with no provider slot of its own. This is the opposite direction: bytes become
62
+ * text. The two are unrelated and nothing routes between them. (There WAS an
63
+ * `EngineCapability.DOCUMENT_GENERATION` that this paragraph used to name; it was withdrawn
64
+ * because no provider capability could ever fill it.)
63
65
  *
64
66
  * ## Absence is benign, and that is load-bearing
65
67
  *
@@ -86,8 +88,26 @@ export enum EngineCapability {
86
88
  */
87
89
  AI_CODING_AGENT = 'AI_CODING_AGENT',
88
90
 
89
- DOCUMENT_GENERATION = 'DOCUMENT_GENERATION',
90
- ANTIVIRUS_SCANNING = 'ANTIVIRUS_SCANNING',
91
+ /*
92
+ * WITHDRAWN 2026-09-03: `DOCUMENT_GENERATION` and `ANTIVIRUS_SCANNING` were members here and are
93
+ * not any more. Neither could ever be filled — `PROVIDER_CAPABILITY_TO_ENGINE_CAPABILITY` had no
94
+ * entry pointing at either, so no provider capability token could claim the slot — while both were
95
+ * classified `SELECT_ONE`, which asserts that exactly one provider must be selected. Selecting one
96
+ * of zero candidates is not a resolution mode.
97
+ *
98
+ * Both capabilities are real and both are delivered elsewhere, which is why withdrawing the slots
99
+ * costs nothing: antivirus scanning is `InfraCapability.ANTIVIRUS_SCANNING`, fulfilled by ClamAV
100
+ * and consumed by `FileScanningBackendService`; PDF generation is the in-process `pdfTemplates`
101
+ * surface, with `InfraCapability.DOCUMENT_RENDERING` (Gotenberg) provisioned beside it. Neither
102
+ * has an external provider, and neither is planned to.
103
+ *
104
+ * Removing `ANTIVIRUS_SCANNING` also removes a collision: the identical spelling named an engine
105
+ * slot nothing could fill AND a live infra capability, in two packages, so a reader grepping the
106
+ * word landed in whichever they searched first.
107
+ *
108
+ * If a hosted AV or document-rendering vendor is ever adopted, the member comes back WITH its
109
+ * `PROVIDER_CAPABILITY_TO_ENGINE_CAPABILITY` entry and its own JSDoc in the same change.
110
+ */
91
111
 
92
112
  FRONTEND_ERROR_MONITORING = 'FRONTEND_ERROR_MONITORING',
93
113
  FRONTEND_PRODUCT_ANALYTICS = 'FRONTEND_PRODUCT_ANALYTICS',
@@ -0,0 +1,179 @@
1
+ # saas.models.file-upload-grant
2
+
3
+ ## Import Origins
4
+
5
+ - `@wildo-ai/saas-models`
6
+
7
+ ## Source Excerpts
8
+
9
+ ### Origin Package: `@wildo-ai/saas-models`
10
+
11
+ ```typescript
12
+ *
13
+ * Lifetime bounds of an upload grant, in minutes. The ceiling is fixed by the framework and enforced
14
+ * when the grant is minted — a request above it is REFUSED, never clamped, so a caller that asked for
15
+ * two hours learns from an error that the bound is sixty minutes rather than from an expiry it did not
16
+ * expect. The bound is the framework's to own because the grant is designed to leave the trust
17
+ * boundary: it lands in an AI agent's transcript, a model provider's logs, a shell history.
18
+ */
19
+ export const FILE_UPLOAD_GRANT_DEFAULT_MINUTES = 15;
20
+ export const FILE_UPLOAD_GRANT_ABSOLUTE_MAX_MINUTES = 60;
21
+
22
+ /**
23
+ * Which write the grant is for. A grant minted on the CREATE upload route uploads a file that a
24
+ * later CREATE will reference; one minted on the UPDATE route (`…/{resourceId}/files/<field>`) is
25
+ * bound to that row. The two routes authorize differently, so a grant may not cross from one to the
26
+ * other — the upload middleware checks this against the route it is presented on.
27
+ */
28
+ export const FILE_UPLOAD_GRANT_OPERATIONS = [CoreResourceOperation.CREATE, CoreResourceOperation.UPDATE] as const;
29
+ export type FileUploadGrantOperation = (typeof FILE_UPLOAD_GRANT_OPERATIONS)[number];
30
+ /** Derived from `CoreResourceOperation` — the named source — rather than a second enum spelling the same two words. */
31
+ export const FileUploadGrantOperationSchema: z.ZodEnum<{ [K in FileUploadGrantOperation]: K }> = z.enum(FILE_UPLOAD_GRANT_OPERATIONS);
32
+
33
+ /**
34
+ * Lifecycle of a grant as the status read reports it. Derived from the token row — `isConsumed`,
35
+ * `expiresAt`, `revokedAt` — never stored, so it cannot drift from the row.
36
+ */
37
+ export enum FileUploadGrantState {
38
+ /** Minted, unexpired, unrevoked, not yet redeemed: an upload will be accepted. */
39
+ PENDING = 'pending',
40
+ /** Redeemed by exactly one upload. `file` names what it produced when the write-back succeeded. */
41
+ REDEEMED = 'redeemed',
42
+ /** Past `expiresAt` without being redeemed. Mint a new one. */
43
+ EXPIRED = 'expired',
44
+ /** Revoked by the minter or an administrator before redemption. */
45
+ REVOKED = 'revoked',
46
+ }
47
+ export const FileUploadGrantStateSchema: z.ZodEnum<typeof FileUploadGrantState> = z.enum(FileUploadGrantState);
48
+
49
+ /**
50
+ * The `metadata` a FILE_UPLOAD_GRANT token carries — the ROUTE binding, as opposed to the identity
51
+ * the typed token fields carry. The upload middleware reads this; the execution-context creator
52
+ * deliberately does not.
53
+ */
54
+ export const FileUploadGrantMetadataSchema: z.ZodObject<{
55
+ fieldName: z.ZodString;
56
+ operation: z.ZodEnum<{ [K in FileUploadGrantOperation]: K }>;
57
+ minter: z.ZodObject<{ entityType: z.ZodString; id: z.ZodString }>;
58
+ uploadUrl: z.ZodString;
59
+ producedFileId: z.ZodOptional<z.ZodString>;
60
+ }> = z.object({
61
+ /** The `z_file()` field the upload lands on, as authored (dotted for nested fields). */
62
+ fieldName: z.string().min(1),
63
+ operation: FileUploadGrantOperationSchema,
64
+ /**
65
+ * Who minted — recorded so the uploaded file is attributed to a PERSON or MACHINE, not to the
66
+ * grant. `entityType` is a `FileUploaderEntityType` value; kept as a string here because the
67
+ * uploader enum lives in `zod-decorators`, upstream of this package.
68
+ */
69
+ minter: z.object({ entityType: z.string().min(1), id: z.string().min(1) }),
70
+ /** The concrete upload URL the grant was minted for — recorded so the status read can hand it to the drop page. */
71
+ uploadUrl: z.string().url(),
72
+ /** Written after a successful redemption; absent until then. */
73
+ producedFileId: z.string().min(1).optional(),
74
+ });
75
+ export type FileUploadGrantMetadata = z.infer<typeof FileUploadGrantMetadataSchema>;
76
+
77
+ /**
78
+ * What a mint returns — identical on the REST door and the MCP tool. Two affordances for one
79
+ * token: `uploadCommand` for a caller that can execute, `uploadPageUrl` for one that must hand a
80
+ * human a link. The token appears in `uploadHeader.value` and inside both commands and the page URL;
81
+ * it is the credential and cannot be omitted. It never appears in any audit row.
82
+ */
83
+ export const FileUploadGrantSchema: z.ZodObject<{
84
+ grantId: z.ZodString;
85
+ state: z.ZodEnum<typeof FileUploadGrantState>;
86
+ expiresAt: z.ZodString;
87
+ singleUse: z.ZodLiteral<true>;
88
+ target: z.ZodObject<{
89
+ resourceType: z.ZodString;
90
+ fieldName: z.ZodString;
91
+ operation: z.ZodEnum<{ [K in FileUploadGrantOperation]: K }>;
92
+ resourceId: z.ZodNullable<z.ZodString>;
93
+ }>;
94
+ constraints: z.ZodObject<{
95
+ maxBytes: z.ZodNumber;
96
+ allowedMimeTypes: z.ZodArray<z.ZodString>;
97
+ }>;
98
+ uploadUrl: z.ZodString;
99
+ uploadHeader: z.ZodObject<{ name: z.ZodString; value: z.ZodString }>;
100
+ uploadCommand: z.ZodString;
101
+ uploadCommandPowerShell: z.ZodString;
102
+ uploadPageUrl: z.ZodNullable<z.ZodString>;
103
+ statusUrl: z.ZodString;
104
+ note: z.ZodString;
105
+ }> = z.object({
106
+ grantId: z.string().min(1),
107
+ state: FileUploadGrantStateSchema,
108
+ expiresAt: z.string().datetime(),
109
+ singleUse: z.literal(true),
110
+ target: z.object({
111
+ resourceType: z.string().min(1),
112
+ fieldName: z.string().min(1),
113
+ operation: FileUploadGrantOperationSchema,
114
+ resourceId: z.string().min(1).nullable(),
115
+ }),
116
+ /** From the field's own constraint resolver — the same one the upload enforces, so the two cannot disagree. */
117
+ constraints: z.object({
118
+ maxBytes: z.number().int().positive(),
119
+ /** Empty means every type is accepted. */
120
+ allowedMimeTypes: z.array(z.string()),
121
+ }),
122
+ uploadUrl: z.string().url(),
123
+ /** The credential travels in a HEADER on the curl form: paths are logged by every proxy, headers are not. */
124
+ uploadHeader: z.object({ name: z.string().min(1), value: z.string().min(1) }),
125
+ /** No `-f`: on a refusal the JSON error body is the only thing that tells the caller why. */
126
+ uploadCommand: z.string().min(1),
127
+ /** In PowerShell `curl` aliases Invoke-WebRequest, which does not understand `-F`; the real binary is `curl.exe`. */
128
+ uploadCommandPowerShell: z.string().min(1),
129
+ /** `null` when the application declares no frontend service — a headless API has no page to hand a human. */
130
+ uploadPageUrl: z.string().url().nullable(),
131
+ statusUrl: z.string().url(),
132
+ note: z.string().min(1),
133
+ });
134
+ export type FileUploadGrant = z.infer<typeof FileUploadGrantSchema>;
135
+
136
+ /**
137
+ * What the public status read returns. The token is the credential, so the read is unauthenticated
138
+ * and returns only what the drop page needs to render and the agent needs to learn the `fileId`:
139
+ * never the file's name (the status URL may be pasted around).
140
+ */
141
+ export const FileUploadGrantStatusSchema: z.ZodObject<{
142
+ grantId: z.ZodString;
143
+ state: z.ZodEnum<typeof FileUploadGrantState>;
144
+ expiresAt: z.ZodString;
145
+ target: z.ZodObject<{
146
+ resourceType: z.ZodString;
147
+ fieldName: z.ZodString;
148
+ operation: z.ZodEnum<{ [K in FileUploadGrantOperation]: K }>;
149
+ resourceId: z.ZodNullable<z.ZodString>;
150
+ }>;
151
+ constraints: z.ZodObject<{ maxBytes: z.ZodNumber; allowedMimeTypes: z.ZodArray<z.ZodString> }>;
152
+ uploadUrl: z.ZodString;
153
+ uploadHeaderName: z.ZodString;
154
+ file: z.ZodNullable<z.ZodObject<{ fileId: z.ZodString; status: z.ZodEnum<typeof FileStatus> }>>;
155
+ }> = z.object({
156
+ grantId: z.string().min(1),
157
+ state: FileUploadGrantStateSchema,
158
+ expiresAt: z.string().datetime(),
159
+ target: z.object({
160
+ resourceType: z.string().min(1),
161
+ fieldName: z.string().min(1),
162
+ operation: FileUploadGrantOperationSchema,
163
+ resourceId: z.string().min(1).nullable(),
164
+ }),
165
+ constraints: z.object({ maxBytes: z.number().int().positive(), allowedMimeTypes: z.array(z.string()) }),
166
+ uploadUrl: z.string().url(),
167
+ /** The page sets this header itself; the token it already holds is the value. */
168
+ uploadHeaderName: z.string().min(1),
169
+ /** `null` until redeemed, or when the post-redemption write-back failed (re-read the resource instead). */
170
+ file: z.object({ fileId: z.string().min(1), status: z.enum(FileStatus) }).nullable(),
171
+ });
172
+ export type FileUploadGrantStatus = z.infer<typeof FileUploadGrantStatusSchema>;
173
+
174
+ /** Body accepted by both mint doors. */
175
+ export const FileUploadGrantMintRequestSchema: z.ZodObject<{ expiresInMinutes: z.ZodOptional<z.ZodNumber> }> = z.object({
176
+ expiresInMinutes: z.number().int().min(1).max(FILE_UPLOAD_GRANT_ABSOLUTE_MAX_MINUTES).optional(),
177
+ }).strict();
178
+ export type FileUploadGrantMintRequest = z.infer<typeof FileUploadGrantMintRequestSchema>;
179
+ ```
@@ -0,0 +1,124 @@
1
+ # saas.models.navigation.surface-vocabulary
2
+
3
+ ## Import Origins
4
+
5
+ - `@wildo-ai/saas-models`
6
+
7
+ ## Source Excerpts
8
+
9
+ ### Origin Package: `@wildo-ai/saas-models`
10
+
11
+ ```typescript
12
+ */
13
+ export enum NavigationZoneName {
14
+ /** Main content area. Lists, root-level reads, primary workspace. Always exists. */
15
+ PRIMARY = 'primary',
16
+ /**
17
+ * First adjacent zone. Detail content in list-detail patterns.
18
+ * Only exists if declared in config. Appears when a `split` transition targets it.
19
+ * Typical use: showing item details alongside a list.
20
+ */
21
+ SECONDARY = 'secondary',
22
+ /**
23
+ * Persistent supplementary content. Reference panels, docs, notes, threads.
24
+ * Only exists if declared in config. Usually hidden by default (`defaultVisible: false`).
25
+ * Activated by `split` with `persistent: true` or explicit user toggle.
26
+ * Typical use: Slack thread panel, VS Code terminal, documentation sidebar.
27
+ */
28
+ COMPANION = 'companion',
29
+ }
30
+
31
+ /**
32
+ * How a zone manages multiple items. Orthogonal to transitions.
33
+ *
34
+ * The transition says "content arrives" — the content model says
35
+ * "how does the zone accommodate it." Any zone can use any content model,
36
+ * regardless of which transitions it supports.
37
+ */
38
+ export enum NavigationZoneContentModel {
39
+ /**
40
+ * Navigation stack: new content pushes on top, previous preserved underneath.
41
+ * Only one item visible at a time. Back navigation pops the stack.
42
+ * `replace` replaces the top without adding to the stack.
43
+ * This is the default for all zones.
44
+ */
45
+ SINGLE = 'single',
46
+ /**
47
+ * Parallel tabs: `push` creates a new tab (or activates existing for the same resource).
48
+ * Tab bar is visible, showing all open tabs. No depth stack within tabs.
49
+ * `replace` replaces the active tab's content. Close is an explicit action (not back).
50
+ * When no tabs remain, `onEmpty` behavior applies.
51
+ */
52
+ TABBED = 'tabbed',
53
+ }
54
+
55
+ /**
56
+ * Responsive collapse behavior when viewport shrinks below a zone's breakpoint.
57
+ *
58
+ * Only applies to secondary and companion zones. Primary never collapses.
59
+ * When viewport grows back past the breakpoint, collapsed content migrates
60
+ * back to its original zone (content is preserved).
61
+ */
62
+ export enum ResponsiveCollapseMode {
63
+ /**
64
+ * Zone hides. Its content joins primary's navigation stack.
65
+ * The user sees the content in-context within primary.
66
+ * Back navigation pops back to primary's previous content.
67
+ */
68
+ PUSH = 'push',
69
+ /**
70
+ * Zone hides. Its content opens as an overlay on top of primary.
71
+ * The user sees the content as a floating sheet/dialog.
72
+ * Dismiss returns to the underlying primary content.
73
+ */
74
+ OVERLAY = 'overlay',
75
+ }
76
+ ```
77
+
78
+ ### Origin Package: `@wildo-ai/saas-models`
79
+
80
+ ```typescript
81
+ *
82
+ * Visual presentation for overlay transitions.
83
+ * Determines how floating content renders above the layout.
84
+ */
85
+ export enum OverlayAppearance {
86
+ /**
87
+ * Centered modal dialog with backdrop.
88
+ * Best for focused tasks: create forms, confirmations, destructive actions.
89
+ * Blocks underlying content visually. Escape or backdrop click dismisses.
90
+ */
91
+ DIALOG = 'dialog',
92
+ /**
93
+ * Side or bottom drawer panel that slides in from an edge.
94
+ * Best for contextual content that benefits from seeing the underlying layout.
95
+ * Less disruptive than dialog. Common for detail views on mobile.
96
+ */
97
+ SHEET = 'sheet',
98
+ /**
99
+ * Vaul-backed mobile drawer.
100
+ * Use when the navigation resolver should choose a drawer directly rather
101
+ * than relying on a dialog appearance plus mobileShape policy.
102
+ */
103
+ DRAWER = 'drawer',
104
+ }
105
+
106
+ /**
107
+ * Visual presentation for split transitions.
108
+ * Determines how adjacent zone content renders alongside the source zone.
109
+ */
110
+ export enum SplitAppearance {
111
+ /**
112
+ * Standard vertical side panel.
113
+ * Content appears beside the source zone with a resizable divider.
114
+ * Most common for list-detail patterns.
115
+ */
116
+ PANEL = 'panel',
117
+ /**
118
+ * Horizontal drawer (bottom panel).
119
+ * Content appears below the source zone.
120
+ * Used for companion panels like terminals, output logs, reference docs.
121
+ */
122
+ DRAWER = 'drawer',
123
+ }
124
+ ```
@@ -0,0 +1,99 @@
1
+ # saas.models.navigation.transition-vocabulary
2
+
3
+ ## Import Origins
4
+
5
+ - `@wildo-ai/saas-models`
6
+
7
+ ## Source Excerpts
8
+
9
+ ### Origin Package: `@wildo-ai/saas-models`
10
+
11
+ ```typescript
12
+ */
13
+ export enum NavigationTransition {
14
+ /**
15
+ * Content added to the zone's stack (single) or as a new tab (tabbed).
16
+ * Back navigation pops the stack or switches to the previous tab.
17
+ * URL adds a new path segment.
18
+ */
19
+ PUSH = 'push',
20
+ /**
21
+ * Content replaces the current content in the zone. No stack entry — the previous
22
+ * content is gone from the zone's state (but remains in browser history).
23
+ * URL replaces the current segment.
24
+ */
25
+ REPLACE = 'replace',
26
+ /**
27
+ * Content opens in an adjacent zone (secondary or companion).
28
+ * Creates a side-by-side layout. The source zone's content remains visible.
29
+ * Back navigation un-splits (closes the adjacent zone).
30
+ * URL adds a split segment.
31
+ */
32
+ SPLIT = 'split',
33
+ /**
34
+ * Content opens in a floating layer above the entire layout (dialog, sheet, or drawer).
35
+ * The underlying layout remains visible but non-interactive.
36
+ * Back navigation or Escape dismisses the overlay.
37
+ * URL adds an overlay param/hash.
38
+ */
39
+ OVERLAY = 'overlay',
40
+ /**
41
+ * Element-level transformation within the current view. A specific item in a
42
+ * list/section transforms from one mode to another (read → edit); a CREATE
43
+ * materializes a new element beside the existing ones. The parent view stays,
44
+ * the zone stack is unchanged, and surrounding items remain visible.
45
+ *
46
+ * Fundamentally different from `replace` (which swaps the entire zone content).
47
+ * `inplace` operates at the element level, not the zone level.
48
+ *
49
+ * No lifecycle modifiers (`persistent`/`ephemeral`) are valid on `inplace`.
50
+ * No appearance to configure — the element transforms within its existing slot.
51
+ *
52
+ * **It is the one transition that does not place content in a zone**, which is
53
+ * why the controller hands it to the element-level host
54
+ * (`InPlaceOperationContext`) instead of resolving a target zone for it. That
55
+ * host is provided by the COLLECTION the element belongs to, so a transition
56
+ * resolving to `inplace` on a surface with no collection above it — a detail
57
+ * page, a breadcrumb, a picker — degrades to an OVERLAY.
58
+ *
59
+ * **It is TRANSIENT: no URL, and a reload returns the view to rest.** Earlier
60
+ * revisions of this comment promised a query param (`?editing=<childId>` /
61
+ * `?creating=<resourceType>`) and none was ever written. It is not written now
62
+ * either, and that is a decision rather than an omission: an inline row-edit is
63
+ * a momentary state of a listing, not a place — no comparable admin framework
64
+ * deep-links one, and anything that should survive a reload or a back button
65
+ * wants `push`. `ResourceOperationActionPresentation.INLINE`, the per-operation
66
+ * tier that selects the same host, is transient for the same reason.
67
+ *
68
+ * @example
69
+ * // Click "edit" on a child in parent's inline section → item transforms to edit form
70
+ * transitions: { [CoreResourceOperation.UPDATE]: NavigationTransition.INPLACE }
71
+ *
72
+ * // Click "add" in a relationship section → create form appears inline in the list
73
+ * transitions: { [CoreResourceOperation.CREATE]: NavigationTransition.INPLACE }
74
+ */
75
+ INPLACE = 'inplace',
76
+ /**
77
+ * Escape the current context and open content at primary scope.
78
+ * Abandons the current context: overlays close, companion/secondary dismiss.
79
+ * The promoted content becomes the primary zone's top content.
80
+ *
81
+ * Use case: a link within an overlay should open as a full primary view,
82
+ * or a nested detail in a companion zone should "pop out" to primary.
83
+ *
84
+ * Fundamentally different from `push` (which stays in the current zone) and
85
+ * from `replace` (which replaces content within the same zone). `promote`
86
+ * crosses zones and always targets primary.
87
+ *
88
+ * No lifecycle modifiers (`persistent`/`ephemeral`) are valid on `promote`.
89
+ * No appearance to configure — content fills primary (same as push/replace).
90
+ *
91
+ * URL serialization: full URL change (promoted resource becomes the primary route).
92
+ *
93
+ * @example
94
+ * // From an overlay, a link should open as primary (close overlay, show in primary)
95
+ * transitions: { [CoreResourceOperation.READ]: NavigationTransition.PROMOTE }
96
+ */
97
+ PROMOTE = 'promote',
98
+ }
99
+ ```