@mnstry/atelier 0.2.0-alpha.6 → 0.2.0-alpha.8

package/src/ui/presentation/state.mjs

@@ -0,0 +1,43 @@
+export const stateAxes = Object.freeze(['hovered', 'focused', 'pressed', 'selected', 'disabled', 'pending', 'dragging', 'invalid'])
+export const EDIT_CODE_POINT_LIMIT = 32768
+const toneLabels = Object.freeze({ neutral: '', info: 'Information', warning: 'Warning', danger: 'Attention', success: 'Success' })
+export function toneLabel(tone) {
+  if (!Object.hasOwn(toneLabels, tone)) throw new TypeError('invalid presentation tone')
+  return toneLabels[tone]
+}
+// Delivery is not business success. Describe the settling request's outcome,
+// independently of unrelated failures, and do not hide concurrent deliveries.
+export function deliveryMessage(outcome, pendingCount = 0) {
+  if (!['sending', 'delivered', 'failed', 'suppressed'].includes(outcome) || !Number.isSafeInteger(pendingCount) || pendingCount < 0) throw new TypeError('invalid delivery state')
+  if (outcome === 'sending') return 'Sending request. Awaiting host state.'
+  if (outcome === 'suppressed') return 'Request already pending. No additional request sent.'
+  const message = outcome === 'failed' ? 'Request delivery failed. Host state has not been confirmed.' : 'Request delivered. Awaiting host state.'
+  return message + (pendingCount ? ' Other requests are still pending.' : '')
+}
+// Match the schema's Unicode code-point limit; never truncate a host draft.
+export function editValueError(value) {
+  if (typeof value !== 'string') return 'Draft must be text.'
+  let count = 0
+  for (const point of value) {
+    const code = point.codePointAt(0)
+    if (code >= 0xd800 && code <= 0xdfff) return 'Draft contains an incomplete Unicode character.'
+    if (++count > EDIT_CODE_POINT_LIMIT) return 'Draft exceeds 32768 characters. It remains in the editor; no request was sent.'
+  }
+  return null
+}
+export function presentationState(input = {}) {
+  if (!input || Object.getPrototypeOf(input) !== Object.prototype) throw new TypeError('invalid state')
+  for (const key of Object.keys(input)) if (!stateAxes.includes(key) || typeof input[key] !== 'boolean') throw new TypeError('unknown state axis')
+  return Object.freeze(Object.fromEntries(stateAxes.map(key => [key, input[key] ?? false])))
+}
+export function resizeRequest(width, value) {
+  if (!width || ![width.min, width.max, width.value, value].every(Number.isFinite) || width.min > width.max || width.value < width.min || width.value > width.max) throw new TypeError('invalid resize range')
+  return Math.max(width.min, Math.min(width.max, value))
+}
+export function keyboardResize(width, key, direction = 'ltr') {
+  if (!['ltr', 'rtl'].includes(direction)) throw new TypeError('invalid direction')
+  if (key === 'Home') return resizeRequest(width, width.min)
+  if (key === 'End') return resizeRequest(width, width.max)
+  if (!['ArrowLeft', 'ArrowRight'].includes(key)) return null
+  return resizeRequest(width, width.value + (key === 'ArrowRight' ? 1 : -1) * (direction === 'rtl' ? -1 : 1))
+}

package/src/ui/presentation/styles.mjs

@@ -0,0 +1,67 @@
+import { resolveTokens, tokenVariables } from './tokens.mjs'
+
+export function presentationStyles(theme = 'light', overrides = {}, rootId) {
+  if (rootId !== undefined && !/^[a-z][a-z0-9-]{0,63}$/.test(rootId)) throw new TypeError('invalid style root')
+  const tokens = resolveTokens(theme, overrides)
+  const scope = rootId === undefined ? '[data-ap-root]' : '[data-ap-root="' + rootId + '"]'
+  return scope + '{' + tokenVariables(tokens) + '}\n' + structuralStyles.replaceAll('[data-ap-root]', scope).replaceAll('NARROW_WIDTH', String(tokens.layout.narrow)).replaceAll('HEADING_SCALE', String(tokens.typography.heading / tokens.typography.body)).replaceAll('SMALL_SCALE', String(tokens.typography.small / tokens.typography.body))
+}
+const structuralStyles = String.raw`
+[data-ap-root] { box-sizing:border-box; container-type:inline-size; color:var(--ap-color-text); background:var(--ap-color-page); font-family:var(--ap-typography-family); font-size:var(--ap-typography-body); line-height:var(--ap-typography-line-height); padding:var(--ap-spacing-large); --ap-pad:var(--ap-density-comfortable); }
+[data-ap-root][data-density="compact"] { --ap-pad:var(--ap-density-compact); }
+[data-ap-root] *,[data-ap-root] *::before,[data-ap-root] *::after { box-sizing:border-box; }
+[data-ap-root] [hidden] { display:none !important; }
+[data-ap-root] :is(h1,h2,h3,p,figure,dl) { margin:0 0 var(--ap-spacing-medium); }
+[data-ap-root] h1 { font-size:calc(HEADING_SCALE * 1.3em); }
+[data-ap-root] h2,[data-ap-root] h3 { font-size:calc(HEADING_SCALE * 1em); }
+[data-ap-root] :is(p,li,dd,dt,a,button,label,output) { overflow-wrap:anywhere; }
+[data-ap-root] :is(input,textarea,button) { font:inherit; }
+[data-ap-root] a { color:var(--ap-color-accent); text-underline-offset:.18em; }
+[data-ap-root] :is(button,input,textarea,select,.ap-link) { min-block-size:var(--ap-density-target); min-inline-size:var(--ap-density-target); }
+[data-ap-root] :is(button,.ap-link) { display:inline-flex; align-items:center; justify-content:center; gap:var(--ap-spacing-medium); padding:var(--ap-spacing-medium) var(--ap-spacing-large); color:var(--ap-color-accent); background:var(--ap-color-panel); border:var(--ap-border-width) solid var(--ap-color-border); border-radius:var(--ap-border-radius); cursor:pointer; transition:background-color var(--ap-motion-duration),color var(--ap-motion-duration); }
+[data-ap-root] .ap-link { justify-content:flex-start; text-decoration:underline; border-color:transparent; border-radius:0; background:transparent; }
+[data-ap-root] .ap-skip:not(:focus) { position:absolute; inline-size:1px; block-size:1px; min-inline-size:0; min-block-size:0; padding:0; border:0; overflow:hidden; clip-path:inset(50%); white-space:nowrap; }
+[data-ap-root] .ap-skip:focus { position:fixed; inset-block-start:var(--ap-spacing-large); inset-inline-start:var(--ap-spacing-large); z-index:1; background:var(--ap-color-panel); }
+[data-ap-root] .ap-header { max-inline-size:var(--ap-layout-content); margin-inline:auto; }
+@media (hover:hover) { [data-ap-root] :is(button,.ap-link):not(:disabled):hover { background:var(--ap-color-selected); } }
+[data-ap-root] :is(button,.ap-link):not(:disabled):active { background:var(--ap-color-accent); color:var(--ap-color-on-accent); }
+[data-ap-root] :focus-visible { outline:var(--ap-state-focus-width) solid var(--ap-color-focus); outline-offset:var(--ap-state-focus-offset); }
+[data-ap-root] :disabled { opacity:var(--ap-state-disabled-opacity); cursor:not-allowed; }
+[data-ap-root] [aria-pressed="true"] { background:var(--ap-color-selected); border-width:2px; }
+[data-ap-root] [aria-invalid="true"] { border:2px solid var(--ap-color-danger); }
+[data-ap-root] [data-ap-dragging="true"] { outline:var(--ap-state-focus-width) dashed var(--ap-color-focus); outline-offset:var(--ap-state-focus-offset); }
+[data-ap-root] .ap-error { color:var(--ap-color-danger); }
+[data-ap-root] .ap-muted { color:var(--ap-color-muted); font-size:calc(SMALL_SCALE * 1em); }
+[data-ap-root] .ap-workspace { display:flex; flex-wrap:wrap; gap:var(--ap-spacing-large); max-inline-size:var(--ap-layout-content); margin-inline:auto; align-items:flex-start; }
+[data-ap-root] .ap-pane { flex:var(--ap-pane-weight,1) 1 var(--ap-pane-basis,320px); min-inline-size:min(100%,var(--ap-layout-pane-min)); max-inline-size:100%; padding:var(--ap-pad); background:var(--ap-color-panel); border:var(--ap-border-width) solid var(--ap-color-border); border-radius:var(--ap-border-radius); }
+[data-ap-root] .ap-pane-body { display:grid; gap:var(--ap-spacing-section); }
+[data-ap-root] .ap-pane-header { border-block-end:var(--ap-border-width) solid var(--ap-color-border); margin-block-end:var(--ap-spacing-large); padding-block-end:var(--ap-spacing-medium); }
+[data-ap-root] .ap-block { min-inline-size:0; }
+[data-ap-root] :is(.ap-nav,.ap-actions,.ap-resize) { display:flex; gap:var(--ap-spacing-medium); flex-wrap:wrap; align-items:center; margin-block:var(--ap-spacing-medium); }
+[data-ap-root] .ap-resize input { flex:1; max-inline-size:100%; }
+[data-ap-root] input:not([type=range]),[data-ap-root] textarea { display:block; inline-size:100%; padding:var(--ap-spacing-medium); color:var(--ap-color-text); background:var(--ap-color-panel); border:var(--ap-border-width) solid var(--ap-color-border); border-radius:var(--ap-border-radius); }
+[data-ap-root] input[aria-invalid="true"],[data-ap-root] textarea[aria-invalid="true"] { border:2px solid var(--ap-color-danger); }
+[data-ap-root] textarea { min-block-size:10rem; resize:vertical; }
+[data-ap-root] label { display:block; }
+[data-ap-root] :is(ul,ol) { padding-inline-start:var(--ap-spacing-section); }
+[data-ap-root] li { margin-block:var(--ap-spacing-medium); }
+[data-ap-root] dt { font-weight:600; }
+[data-ap-root] dd { margin-inline-start:0; }
+[data-ap-root] table { border-collapse:collapse; inline-size:100%; table-layout:fixed; }
+[data-ap-root] :is(th,td) { text-align:start; border-block-end:var(--ap-border-width) solid var(--ap-color-border); padding:var(--ap-spacing-medium); overflow-wrap:anywhere; }
+[data-ap-root] pre { white-space:pre-wrap; overflow-wrap:anywhere; font-family:monospace; padding:var(--ap-spacing-medium); border:var(--ap-border-width) solid var(--ap-color-border); }
+[data-ap-root] .ap-diff { display:grid; grid-template-columns:repeat(2,minmax(0,1fr)); gap:var(--ap-spacing-large); }
+[data-ap-root] img { max-inline-size:100%; block-size:auto; }
+[data-ap-root] .ap-notice { border-inline-start:4px solid var(--ap-color-border); padding-inline-start:var(--ap-spacing-large); }
+[data-ap-root] .ap-tone { font-weight:600; }
+[data-ap-root] [data-tone=info],[data-ap-root] [data-tone=warning] { border-color:var(--ap-color-accent); }
+[data-ap-root] [data-tone=warning] { border-inline-start-style:dashed; }
+[data-ap-root] [data-tone=danger] { border-color:var(--ap-color-danger); }
+[data-ap-root] [data-tone=success] { border-color:var(--ap-color-success); }
+[data-ap-root] dialog { max-inline-size:min(36rem,calc(100vw - 2rem)); max-block-size:calc(100dvh - 2rem); overflow:auto; color:var(--ap-color-text); background:var(--ap-color-panel); padding:var(--ap-spacing-section); border:var(--ap-border-width) solid var(--ap-color-border); border-radius:var(--ap-border-radius); box-shadow:0 var(--ap-elevation-offset) var(--ap-elevation-blur) rgb(0 0 0 / var(--ap-elevation-opacity)); }
+[data-ap-root] dialog::backdrop { background:rgb(0 0 0 / .6); }
+@container (max-width:NARROW_WIDTHpx) { [data-ap-root] .ap-workspace { flex-direction:column; } [data-ap-root] .ap-pane { flex:none; inline-size:100%; } [data-ap-root] .ap-resize { display:none; } [data-ap-root] .ap-diff { grid-template-columns:1fr; } }
+@media (prefers-reduced-motion:reduce) { [data-ap-root] *,[data-ap-root] *::before,[data-ap-root] *::after { transition:none !important; animation:none !important; scroll-behavior:auto !important; } }
+@media (forced-colors:active) { [data-ap-root] :focus-visible { outline-color:Highlight; } [data-ap-root] [aria-pressed=true] { border-color:Highlight; } }
+@media print { [data-ap-root] { --ap-color-text:#000;--ap-color-page:#fff;--ap-color-panel:#fff;--ap-color-muted:#333;--ap-color-selected:#fff;--ap-color-accent:#000;--ap-color-danger:#000;--ap-color-success:#000; color:#000;background:#fff;padding:0; } [data-ap-root] :is(.ap-skip,.ap-nav,.ap-resize,button,dialog) { display:none !important; } [data-ap-root] .ap-workspace { display:block; } [data-ap-root] .ap-pane { border:0;break-inside:auto; } [data-ap-root] a { color:#000; } }
+`

package/src/ui/presentation/tokens.mjs

@@ -0,0 +1,74 @@
+const freeze = value => {
+  Object.values(value).forEach(v => { if (v && typeof v === 'object') freeze(v) })
+  return Object.freeze(value)
+}
+
+export const tokenContract = freeze({
+  color: { page: '#f5f6f8', panel: '#ffffff', text: '#18202b', muted: '#495668', accent: '#164fa3', onAccent: '#ffffff', border: '#718096', selected: '#e1ecff', danger: '#a51d32', success: '#21633d', focus: '#164fa3' },
+  typography: { body: 16, small: 14, heading: 22, lineHeight: 1.5, family: 'sans-serif' },
+  spacing: { small: 4, medium: 8, large: 16, section: 24 },
+  layout: { content: 1280, narrow: 768, paneMin: 240 },
+  density: { comfortable: 12, compact: 8, target: 44 },
+  elevation: { offset: 4, blur: 16, opacity: 0.15 },
+  border: { width: 1, radius: 8 },
+  motion: { duration: 120 },
+  state: { focusWidth: 3, focusOffset: 3, disabledOpacity: 0.7 },
+})
+
+const dark = { page: '#141a23', panel: '#202938', text: '#f3f6fb', muted: '#c0cbda', accent: '#a4c6ff', onAccent: '#12213b', border: '#8b9bb1', selected: '#304566', danger: '#ffacb9', success: '#9cdfb1', focus: '#a4c6ff' }
+const range = {
+  'typography.body': [16, 32], 'typography.small': [14, 32], 'typography.heading': [18, 48], 'typography.lineHeight': [1.4, 2],
+  'spacing.small': [2, 16], 'spacing.medium': [4, 32], 'spacing.large': [8, 64], 'spacing.section': [16, 96],
+  'layout.content': [320, 2400], 'layout.narrow': [480, 1200], 'layout.paneMin': [160, 480],
+  'density.comfortable': [8, 24], 'density.compact': [4, 16], 'density.target': [44, 64],
+  'elevation.offset': [0, 16], 'elevation.blur': [0, 40], 'elevation.opacity': [0, 0.4],
+  'border.width': [1, 4], 'border.radius': [0, 24], 'motion.duration': [0, 250],
+  'state.focusWidth': [3, 6], 'state.focusOffset': [2, 6], 'state.disabledOpacity': [0.7, 1],
+}
+export function contrastRatio(a, b) {
+  const lum = hex => {
+    const c = hex.slice(1).match(/../g).map(x => parseInt(x, 16) / 255).map(x => x <= .04045 ? x / 12.92 : ((x + .055) / 1.055) ** 2.4)
+    return c[0] * .2126 + c[1] * .7152 + c[2] * .0722
+  }
+  const x = lum(a), y = lum(b)
+  return (Math.max(x, y) + .05) / (Math.min(x, y) + .05)
+}
+
+export function resolveTokens(theme = 'light', overrides = {}) {
+  if (!['light', 'dark'].includes(theme)) throw new TypeError('unknown theme')
+  if (!overrides || Object.getPrototypeOf(overrides) !== Object.prototype) throw new TypeError('invalid token overrides')
+  const result = structuredClone(tokenContract)
+  if (theme === 'dark') result.color = { ...dark }
+  for (const [group, values] of Object.entries(overrides)) {
+    if (!Object.hasOwn(result, group) || !values || Object.getPrototypeOf(values) !== Object.prototype) throw new TypeError('unknown token group')
+    for (const [key, value] of Object.entries(values)) {
+      if (!Object.hasOwn(result[group], key)) throw new TypeError('unknown token')
+      const bounds = range[group + '.' + key]
+      const valid = group === 'color' ? typeof value === 'string' && /^#[0-9a-f]{6}$/i.test(value)
+        : key === 'family' ? ['sans-serif', 'serif', 'monospace'].includes(value)
+        : bounds && typeof value === 'number' && Number.isFinite(value) && value >= bounds[0] && value <= bounds[1]
+      if (!valid) throw new TypeError('invalid token value')
+      result[group][key] = value
+    }
+  }
+  for (const background of ['page', 'panel', 'selected']) {
+    for (const foreground of ['text', 'muted', 'accent', 'danger', 'success']) {
+      if (contrastRatio(result.color[foreground], result.color[background]) < 4.5) throw new TypeError('text token contrast floor')
+    }
+    for (const foreground of ['border', 'focus']) {
+      if (contrastRatio(result.color[foreground], result.color[background]) < 3) throw new TypeError('boundary token contrast floor')
+    }
+  }
+  if (contrastRatio(result.color.onAccent, result.color.accent) < 4.5) throw new TypeError('accent label contrast floor')
+  return freeze(result)
+}
+
+export function tokenVariables(tokens) {
+  const checked = resolveTokens('light', tokens)
+  const unitless = new Set(['typography.lineHeight', 'elevation.opacity', 'state.disabledOpacity'])
+  return Object.entries(checked).flatMap(([group, values]) => Object.entries(values).map(([key, value]) => {
+    const name = (group + '-' + key).replace(/[A-Z]/g, c => '-' + c.toLowerCase())
+    const suffix = typeof value === 'number' ? unitless.has(group + '.' + key) ? '' : group === 'motion' ? 'ms' : 'px' : ''
+    return '--ap-' + name + ':' + value + suffix
+  })).join(';')
+}

package/src/ui/presentation/web.mjs

@@ -0,0 +1,85 @@
+import { htmlEscape as escape } from '../html-primitives.mjs'
+import { assertPresentation } from './contract.mjs'
+import { presentationStyles } from './styles.mjs'
+import { toneLabel } from './state.mjs'
+
+const domId = (model, kind, id) => escape(model.id + ':' + kind + ':' + id)
+const noticeTypes = new Set(['status', 'refusal', 'decision', 'receipt', 'offer', 'review', 'publication'])
+
+export function renderPresentation(model, { tokenOverrides = {}, interactive = true } = {}) {
+  assertPresentation(model)
+  const nodes = new Map(model.nodes.map(node => [node.id, node]))
+  const renderAction = node => {
+    if (!interactive) return '<p>' + escape(node.label) + ' (host action; unavailable in document)' + (node.reason ? ': ' + escape(node.reason) : '') + '</p>'
+    const name = domId(model, 'node', node.id)
+    const reason = node.reason ? '<p class="ap-muted" id="' + name + ':reason">' + escape(node.reason) + '</p>' : ''
+    return '<div class="ap-action"><button type="button" id="' + name + '" data-ap-action="' + escape(node.id) + '"' +
+      (node.disabled ? ' disabled' : '') + (node.reason ? ' aria-describedby="' + name + ':reason"' : '') +
+      (node.shortcut ? ' aria-keyshortcuts="' + escape(node.shortcut.aria) + '"' : '') + '>' +
+      escape(node.label) + (node.shortcut ? ' <kbd aria-hidden="true">' + escape(node.shortcut.display) + '</kbd>' : '') +
+      '</button>' + reason + '</div>'
+  }
+  const renderNode = node => {
+    const name = domId(model, 'node', node.id), labelId = name + ':label'
+    const heading = '<h3 id="' + labelId + '">' + escape(node.label) + '</h3>'
+    let body
+    if (node.type === 'action') return renderAction(node)
+    if (node.type === 'text') body = '<p>' + escape(node.text) + '</p>'
+    if (node.type === 'preview') body = '<pre>' + escape(node.text) + '</pre>'
+    if (node.type === 'diff') body = '<div class="ap-diff"><div><h4>' + escape(node.beforeLabel) + '</h4><pre>' + escape(node.before) + '</pre></div><div><h4>' + escape(node.afterLabel) + '</h4><pre>' + escape(node.after) + '</pre></div></div>'
+    if (node.type === 'media') body = '<figure><img src="' + escape(node.src) + '" alt="' + escape(node.alt) + '" loading="lazy">' + (node.caption ? '<figcaption>' + escape(node.caption) + '</figcaption>' : '') + '</figure>'
+    if (node.items) {
+      const tag = node.type === 'sequence' ? 'ol' : 'ul'
+      body = '<' + tag + '>' + node.items.map((item, index) => '<li' + (interactive && node.reorderable ? ' draggable="true" data-ap-drag="' + escape(node.id) + '" data-ap-item="' + escape(item.id) + '"' : '') + '>' +
+        (!interactive ? '<span>' + escape(item.label) + (item.selected ? ' (selected)' : '') + '</span>' : item.href ? '<a class="ap-link" href="' + escape(item.href) + '">' + escape(item.label) + '</a>' :
+          '<button type="button" data-ap-select="' + escape(node.id) + '" data-ap-item="' + escape(item.id) + '"' +
+          (typeof item.selected === 'boolean' ? ' aria-pressed="' + item.selected + '"' : '') + '>' + escape(item.label) + '</button>') +
+        (item.detail ? '<p class="ap-muted">' + escape(item.detail) + '</p>' : '') +
+        (interactive && node.reorderable ? '<div class="ap-actions"><button type="button" data-ap-move="' + escape(node.id) + '" data-ap-item="' + escape(item.id) + '" data-ap-position="' + (index - 1) + '"' + (index === 0 ? ' disabled' : '') + ' aria-label="Move ' + escape(item.label) + ' earlier">Move earlier</button><button type="button" data-ap-move="' + escape(node.id) + '" data-ap-item="' + escape(item.id) + '" data-ap-position="' + (index + 1) + '"' + (index === node.items.length - 1 ? ' disabled' : '') + ' aria-label="Move ' + escape(item.label) + ' later">Move later</button></div>' : '') + '</li>').join('') + '</' + tag + '>'
+      if (node.type === 'graph') {
+        const labels = new Map(node.items.map(item => [item.id, item.label]))
+        body += '<table><caption>' + escape(node.label) + ' relationships</caption><thead><tr><th scope="col">From</th><th scope="col">Relationship</th><th scope="col">To</th></tr></thead><tbody>' +
+          node.edges.map(edge => '<tr><td>' + escape(labels.get(edge.from)) + '</td><td>' + escape(edge.label) + '</td><td>' + escape(labels.get(edge.to)) + '</td></tr>').join('') + '</tbody></table>'
+      }
+    }
+    if (noticeTypes.has(node.type)) body = '<div class="ap-notice" data-tone="' + escape(node.tone) + '">' + (toneLabel(node.tone) ? '<p class="ap-tone">' + toneLabel(node.tone) + '</p>' : '') + '<p' + (node.type === 'status' ? ' role="status"' : '') + '>' + escape(node.text) + '</p><dl>' +
+      node.details.map(entry => '<dt>' + escape(entry.label) + '</dt><dd>' + escape(entry.value) + '</dd>').join('') + '</dl><div class="ap-actions">' + node.actions.map(ref => renderAction(nodes.get(ref))).join('') + '</div></div>'
+    if (node.type === 'field' || node.type === 'editor') {
+      if (!interactive) return '<section class="ap-block" id="' + name + '">' + heading + '<pre>' + escape(node.value) + '</pre>' + (node.error ? '<p>' + escape(node.error) + '</p>' : '') + '</section>'
+      const fieldId = name + ':input'
+      const attrs = ' id="' + fieldId + '" data-ap-edit="' + escape(node.id) + '"' +
+        (node.disabled ? ' disabled' : '') + (node.required ? ' required' : '') +
+        (node.error ? ' aria-invalid="true" aria-describedby="' + name + ':error"' : '')
+      const field = node.type === 'editor' ? '<textarea' + attrs + '>' + escape(node.value) + '</textarea>'
+        : '<input type="' + escape(node.input) + '"' + attrs + ' value="' + escape(node.value) + '">'
+      return '<div class="ap-block" id="' + name + '"><label for="' + fieldId + '">' + escape(node.label) + (node.required ? ' (required)' : '') + '</label>' + field +
+        (node.error ? '<p class="ap-error" id="' + name + ':error">' + escape(node.error) + '</p>' : '') +
+        '<p class="ap-error" data-ap-edit-error="' + escape(node.id) + '" id="' + fieldId + ':limit" aria-live="polite" hidden></p></div>'
+    }
+    return '<section class="ap-block" id="' + name + '" aria-labelledby="' + labelId + '">' + heading + body + '</section>'
+  }
+  const primary = model.panes.find(pane => pane.role === 'primary')
+  const totalWeight = model.panes.reduce((sum, pane) => sum + (pane.width?.value ?? 50), 0)
+  const nav = model.navigation.map(item => '<a class="ap-link" href="#' + domId(model, 'pane', item.target) + '">' + escape(item.label) + '</a>').join('')
+  const panes = model.panes.map(pane => {
+    const weight = pane.width?.value ?? 50, share = weight / totalWeight
+    const name = domId(model, 'pane', pane.id), heading = name + ':label'
+    const resize = interactive && pane.width ? '<div class="ap-resize"><label for="' + name + ':resize">Width of ' + escape(pane.label) + '</label><input id="' + name + ':resize" type="range" data-ap-resize="' + escape(pane.id) + '" min="' + pane.width.min + '" max="' + pane.width.max + '" value="' + pane.width.value + '" aria-controls="' + name + '"><button type="button" data-ap-step="' + escape(pane.id) + '" data-ap-delta="-1" aria-label="Decrease width of ' + escape(pane.label) + '">−</button><button type="button" data-ap-step="' + escape(pane.id) + '" data-ap-delta="1" aria-label="Increase width of ' + escape(pane.label) + '">+</button></div>' : ''
+    return '<section class="ap-pane" id="' + name + '" tabindex="-1" aria-labelledby="' + heading + '" data-ap-pane="' + escape(pane.id) + '"' +
+      ' style="--ap-pane-weight:' + weight + ';--ap-pane-basis:calc(' + (share * 100) + '% - var(--ap-spacing-large) * ' + ((model.panes.length - 1) * share) + ')"' + '><header class="ap-pane-header"><h2 id="' + heading + '">' + escape(pane.label) + '</h2>' + resize + '</header><div class="ap-pane-body">' +
+      pane.blocks.map(ref => renderNode(nodes.get(ref))).join('') + '</div></section>'
+  }).join('')
+  return '<div data-ap-root="' + escape(model.id) + '" data-density="' + escape(model.density) + '" dir="' + escape(model.direction) + '" lang="' + escape(model.lang) + '"><style>' + presentationStyles(model.theme, tokenOverrides, model.id) + '</style>' +
+    '<a class="ap-link ap-skip" href="#' + domId(model, 'pane', primary.id) + '">Skip to ' + escape(primary.label) + '</a><header class="ap-header"><h1>' + escape(model.title) + '</h1><nav class="ap-nav" aria-label="Workspace">' + nav + '</nav></header>' +
+    '<main class="ap-workspace">' + panes + '</main><output data-ap-delivery aria-live="polite"></output>' +
+    (interactive ? '<dialog data-ap-confirm aria-labelledby="' + escape(model.id) + ':confirm:title" aria-describedby="' + escape(model.id) + ':confirm:description"><h2 id="' + escape(model.id) + ':confirm:title" data-ap-confirm-title></h2><p id="' + escape(model.id) + ':confirm:description" data-ap-confirm-description></p><div class="ap-actions"><button type="button" data-ap-cancel autofocus>Cancel</button><button type="button" data-ap-confirm-action>Continue</button></div></dialog>' : '') + '</div>'
+}
+
+export function renderPresentationDocument(model, options = {}) {
+  assertPresentation(model)
+  return '<!doctype html><html lang="' + escape(model.lang) + '" dir="' + escape(model.direction) + '"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>' + escape(model.title) + '</title></head><body>' + renderPresentation(model, options) + '</body></html>'
+}
+
+export function renderReadOnlyDocument(model, options = {}) {
+  return renderPresentationDocument(model, { ...options, interactive: false })
+}

package/src/ui/review-page.mjs

@@ -0,0 +1,32 @@
+export function renderReviewPage() {
+  return `<!doctype html><html lang="en"><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><title>Review workspace</title>
+<style>body{font:18px/1.6 system-ui;max-width:850px;margin:3rem auto;padding:0 1.5rem;color:#202524;background:#faf9f5}h1,h2{line-height:1.2}label{display:block;margin-top:1rem}input,textarea,select,button{font:inherit;padding:.5rem;max-width:100%;box-sizing:border-box}textarea{width:100%;min-height:7rem}button{cursor:pointer;margin:.5rem .5rem .5rem 0}button:focus-visible,input:focus-visible,textarea:focus-visible,select:focus-visible{outline:3px solid #1c695c;outline-offset:3px}pre{white-space:pre-wrap;overflow-wrap:anywhere;background:#eee;padding:1rem}article{border-top:1px solid #b8b8af;padding:1rem 0}.note{color:#49534e}#status{position:sticky;top:0;background:#faf9f5;padding:.5rem;border-bottom:1px solid #aaa}</style>
+<h1>Review workspace</h1><p class="note">Questions and corrections stay yours. Decisions record local judgment; source changes require a separate owner action.</p>
+<p id="status" role="status" aria-live="polite">Ready to open a document or a run.</p>
+<label>Your name <input id="reviewer" autocomplete="name"></label><p class="note">Recorded as locally asserted identity.</p>
+<h2>Read and respond</h2><form id="open-document"><label>Repository <input id="repo" required></label><label>Document path <input id="path" required placeholder="README.md"></label><button>Open document</button></form>
+<pre id="document" tabindex="0" aria-label="Source document"></pre>
+<label>Passage (copy its exact wording)<textarea id="anchor"></textarea></label>
+<label>Response type<select id="response-type"><option value="question">Question</option><option value="correction">Correction</option><option value="discussion">Discuss</option></select></label>
+<label>Your response<textarea id="wording"></textarea></label><button id="save-response">Save response</button><button id="save-position">Save reading position</button>
+<h2>Review a run</h2><form id="open-run"><label>Run ID <input id="run-id" required></label><button>Open run</button></form><div id="run"></div>
+<h2>Recorded contributions</h2><p>Viewing a document does not record agreement. Old responses remain attached to their original revision.</p><div id="history"></div>
+<script type="module">
+const el=id=>document.getElementById(id);let nonce='',doc=null,run=null,history=[],pending=null,responseTarget='response-'+crypto.randomUUID();
+const drafts=new Map();
+const status=message=>el('status').textContent=message;
+async function request(url,body){if(!url.startsWith('/api/review/'))throw new Error('Invalid local route');
+const options=body?{method:'POST',headers:{'Content-Type':'application/json','X-Atelier-Nonce':nonce},body:JSON.stringify(body)}:{};
+const response=await fetch('/api/review/'+url.slice('/api/review/'.length),options);const result=await response.json();if(!response.ok||!result.ok)throw new Error(result.error||'Request failed');return result}
+async function auth(){nonce=(await request('/api/review/session',{})).mutationNonce}
+function para(parent,text){const p=document.createElement('p');p.textContent=text;parent.append(p);return p}
+async function refresh(){history=(await request('/api/review/records')).records;el('history').replaceChildren();for(const record of history){const a=document.createElement('article');para(a,record.input.kind+' · asserted by '+record.identity.name+' · '+record.recordedAt);para(a,record.input.wording||record.input.rationale||'Reading position saved');para(a,'Revision: '+(record.input.documentDigest||record.input.evidenceDigest));if(record.input.anchor)para(a,record.input.anchor);if(record.input.kind==='position'){const resume=document.createElement('button');resume.textContent='Resume '+record.input.repo+'/'+record.input.path;resume.onclick=()=>{el('repo').value=record.input.repo;el('path').value=record.input.path;el('open-document').requestSubmit()};a.append(resume)}if(record.input.kind==='decision'){para(a,'Decision: '+record.input.decision+' · claim '+record.input.targetId+' · version '+record.version);if(record.input.revision)para(a,'Proposed successor wording: '+record.input.revision);if(record.input.decision==='accepted'){const button=document.createElement('button');button.textContent='Inspect owner handoff';button.onclick=async()=>{try{const result=await request('/api/review/handoff?'+new URLSearchParams({id:record.input.requestId}));const pre=document.createElement('pre');pre.textContent=JSON.stringify(result,null,2);a.append(pre)}catch(error){status(error.message)}};a.append(button)}}el('history').append(a)}}
+function version(kind,targetId,extra){return history.filter(r=>r.input.kind===kind&&r.input.targetId===targetId&&(r.input.runId||null)===(extra.runId||null)&&(r.input.repo||null)===(extra.repo||null)&&(r.input.path||null)===(extra.path||null)&&(kind!=='position'||r.input.reviewer===el('reviewer').value.trim())).length}
+async function save(kind,targetId,extra){const input={kind,targetId,expectedVersion:version(kind,targetId,extra),reviewer:el('reviewer').value.trim(),...extra};const fingerprint=JSON.stringify(input);if(!pending||pending.fingerprint!==fingerprint)pending={fingerprint,input:{...input,requestId:crypto.randomUUID()}};const attempt=pending;status('Saving…');try{await auth();await request('/api/review/contributions',attempt.input);if(pending===attempt)pending=null;status('Saved to local history.');await refresh().catch(()=>status('Saved; history refresh unavailable.'));return true}catch(error){const recovery=error.message.includes('stale contribution version')?'Reopen the run to inspect newer decisions before saving again.':error.message.includes('document changed')?'Reopen the document and explicitly select a passage in its new revision.':error.message.includes('claim evidence changed')?'Create a new run against current evidence before deciding.':'Retry with Save after the active writer or service is available.';status('Not confirmed saved: '+error.message+'. Your wording remains here. '+recovery)}}
+el('open-document').onsubmit=async event=>{event.preventDefault();try{const repo=el('repo').value,path=el('path').value;const loaded=await request('/api/review/document?'+new URLSearchParams({repo,path}));doc={repo,path,...loaded};el('document').textContent=doc.text;await refresh();const positions=history.filter(r=>r.input.kind==='position'&&r.input.repo===repo&&r.input.path===path&&r.input.documentDigest===doc.digest&&r.input.reviewer===el('reviewer').value.trim());const last=positions.at(-1);if(last){el('anchor').value=last.input.anchor;const range=document.createRange();const node=el('document').firstChild;range.setStart(node,Math.min(last.input.position,node.length));range.collapse(true);const selection=window.getSelection();selection.removeAllRanges();selection.addRange(range);el('document').focus();const rect=range.getBoundingClientRect();if(rect.height)window.scrollBy(0,rect.top-window.innerHeight/3)}status('Document opened. Previous contributions are listed below.')}catch(error){status(error.message)}};
+el('save-response').onclick=async()=>{if(!doc)return status('Open a document first.');if(await save('response',responseTarget,{repo:doc.repo,path:doc.path,documentDigest:doc.digest,anchor:el('anchor').value,responseType:el('response-type').value,wording:el('wording').value})){el('wording').value='';responseTarget='response-'+crypto.randomUUID()}};
+el('save-position').onclick=()=>{if(!doc)return status('Open a document first.');const anchor=el('anchor').value;return save('position','reading-position',{repo:doc.repo,path:doc.path,documentDigest:doc.digest,anchor,position:Math.max(0,doc.text.indexOf(anchor))})};
+el('open-run').onsubmit=async event=>{event.preventDefault();try{run=await request('/api/review/run?'+new URLSearchParams({id:el('run-id').value}));await refresh();el('run').replaceChildren();para(el('run'),'Answer completeness: '+run.run.score+'%. This is not evidence confidence or runtime readiness.');para(el('run'),run.current?'Evidence currently matches.':'Historical evidence: current acceptance unavailable.');for(const [index,claim] of run.run.claims.entries()){const a=document.createElement('article');para(a,claim.subject+' — '+claim.predicate+' — '+claim.object);para(a,'Claim ID: '+claim.claimId);para(a,claim.notes.join(' '));const mapped=run.snapshot.claimEvidence[index];para(a,'Mapped evidence: '+mapped.status);for(const source of mapped.resolved){para(a,source.id+' · '+source.repo+'/'+source.path);para(a,source.excerpt)}if(mapped.unresolved.length)para(a,'Unresolved references: '+mapped.unresolved.join(', '));para(a,'Evidence: operator answers and the recorded source inventory. Source presence alone does not substantiate this relationship.');const details=document.createElement('details');const summary=document.createElement('summary');summary.textContent='Inspect recorded inputs and source identities';details.append(summary);const pre=document.createElement('pre');pre.textContent=JSON.stringify({mapping:mapped,answers:run.snapshot.answers,sources:run.snapshot.sources,limitations:run.snapshot.limitations},null,2);details.append(pre);a.append(details);para(a,'Acceptance records your judgment and prepares an owner handoff. It does not apply, publish or promote the claim.');const label=document.createElement('label');label.textContent='Reason or proposed revision';const reason=document.createElement('textarea');const draftKey=run.run.runId+':'+claim.claimId;reason.value=drafts.get(draftKey)||'';reason.oninput=()=>drafts.set(draftKey,reason.value);label.append(reason);a.append(label);for(const decision of ['accepted','rejected','revised']){const button=document.createElement('button');button.textContent={accepted:'Accept',rejected:'Reject',revised:'Propose revision'}[decision];button.disabled=!run.current||(decision==='accepted'&&(mapped.status!=='linked-source'||run.run.blockers.length>0));button.onclick=()=>save('decision',claim.claimId,{runId:run.run.runId,evidenceDigest:run.snapshot.digest,decision,rationale:reason.value,...(decision==='revised'?{revision:reason.value}:{})});a.append(button)}el('run').append(a)}}catch(error){status(error.message)}};
+refresh().catch(error=>status('History unavailable: '+error.message));
+</script></html>`
+}

package/src/upgrade/explanation.mjs

@@ -0,0 +1,33 @@
+// Quote data as Markdown text, including control characters in path names.
+const quote = (value) => JSON.stringify(value)
+  .replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;')
+  .replace(/[\\`*_{}\[\]()#+.!|]/g, '\\$&')
+
+export function renderUpgradeExplanation(report) {
+  return [
+    '# Atelier upgrade for review',
+    '',
+    `Plan: ${quote(report.planDigest)}`,
+    `Source commit: ${quote(report.baseHead)}`,
+    `Candidate branch: ${quote(report.branch)}`,
+    `Expires: ${quote(report.expiresAt)}`,
+    '',
+    report.bindingsCurrent ? 'The saved plan matches the observed workspace. This report does not record approval.' : 'The saved plan cannot currently be applied:',
+    ...report.blockers.map((reason) => `- ${quote(reason)}`),
+    '',
+    '## Proposed changes',
+    ...report.writes.map((write) => `- ${quote(write.action)} ${quote(write.path)} (${quote(write.owner)}): ${quote(write.before?.digest ?? 'absent')} → ${quote(write.after.digest)}; mode ${quote(write.after.mode)}.`),
+    '',
+    '## Consent and outcome',
+    'Approval covers these prepared lock/projection bytes and a local Git commit through existing hooks. The source branch remains unchanged.',
+    'Package installation, merge, publication and service activation require their own named authority. This report does not authorize any action.',
+    'The digest identifies content; the agent must obtain and retain the owner decision. The CLI does not authenticate human approval.',
+    '',
+    `Recovery: ${report.recovery}.`,
+    ...report.caveats.map((note) => `- ${note}`),
+    '',
+    `Installed executor evidence: ${quote(report.provenance.executorDigest)}`,
+    `Source inventory: ${report.provenance.sourceFiles} files. Upstream release authentication: not supplied by this transaction.`,
+    '',
+  ].join('\n')
+}