@accelflow/space-content 0.0.0-stage → 0.1.0-beta.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Accelflow Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,118 @@
-# Temporary Holding Version
+# Space build content SDK
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Node 24+ build-time content synchronization for Space Headless CMS, with optional browser-safe table-of-contents presentation. Licensed under MIT.
+
+The beta package is available on npm.
+
+```sh
+npm install @accelflow/space-content@beta
+```
+
+```js
+import { syncContent } from '@accelflow/space-content/node';
+```
+
+Run content synchronization before your site's build. The `/node` entry is server-only; never include it or a Workspace token in a browser bundle.
+
+Use `SPACE_API_URL`, `SPACE_DOWNLOAD_ORIGIN`, `SPACE_ACCOUNT_ID`,
+`SPACE_WORKSPACE_ID`, `SPACE_BUILD_TOKEN` as server-only environment variables.
+IDs are stable account/workspace IDs, not slugs. `.space-cache`, `.space-build`,
+`.generated` must be ignored by Git and excluded from public deployment except
+for the intentionally generated content consumed by the site.
+
+`syncContent()` returns a fresh `snapshotDir` with `content.json` and
+`space-assets/<sha256>`. `content.json` contains selected HTML **or** structured
+JSON, title, slug, article metadata and an attachment ID/hash/MIME mapping.
+HTML attachment references use `/space-assets/<sha256>`; serve these files with
+the indicated MIME types. JSON rendering must resolve attachment IDs through
+that mapping. Internal article links retain published paths; the site's route
+mapping must match or transform them. Place static assets at the domain root,
+or rewrite those URLs for a subpath deployment.
+
+Vite integration: run sync as the first build script, import the generated JSON,
+and render it using the site's SSG/prerender tool. Vite alone does not create
+article HTML pages. Next.js integration: import generated JSON in server build
+code, use its article slugs in `generateStaticParams`, metadata in
+`generateMetadata`, and render the chosen body format. Plain Node integration
+keeps both frameworks independent of SDK-specific runtime plugins.
+
+The cache directory must be private and trusted, with no untrusted ancestor
+symlinks. Share it only among trusted builds for this environment. Content is
+hash-verified on every reuse and namespaced by account/workspace/format/schema.
+Each build gets a new output generation; removed articles/assets are excluded.
+Do not glob the cache as public content. Cache/output cleanup is the CI owner's
+responsibility and must not remove running jobs' files.
+
+A build and each new batch connection are authorized. An admitted stream may
+finish after token deletion, up to its deadline. Reconnecting requires current
+authorization. Verified complete objects survive a transport retry; partial
+objects restart. Missing terminal markers, checksum failures, foreign objects,
+or schema errors fail the build. No stale/offline fallback is used.
+
+Transport limits: 4,096 unique objects per snapshot, 250,000,000 bytes per object,
+1 GiB per snapshot. Space applies the effective plan at upload (Free 10 MB, Team
+50 MB, Enterprise 250 MB, decimal bytes). Delivery accepts those admitted files;
+it does not re-count them as new storage usage or apply a lower per-file quota.
+The snapshot budget is a separate operational limit. Large objects stream to disk;
+complete objects are hash-verified before cache reuse. Partial objects restart on
+retry (default 2 retries). Cache GC and snapshot sharding remain host responsibilities.
+Large attachments require the matching Space delivery service update.
+
+Tests: `npm ci --ignore-scripts` then `npm test` from this repository root.
+Server, Worker and real-cloud integration tests remain in the Space service
+repository; the tests here exercise the client with synthetic protocol fixtures.
+
+## Full framework examples
+
+See [Vite and Next.js examples](examples/README.md) for complete static builds,
+CI cache handling, HTML rendering, asset headers and deployment boundaries.
+
+## Table of contents
+
+The browser-safe entry is separate from the authenticated Node client:
+
+```js
+import { mountTableOfContents } from '@accelflow/space-content/toc';
+import '@accelflow/space-content/toc.css';
+
+const cleanup = mountTableOfContents(articleElement, { locale: 'ja' });
+// Call cleanup when replacing the article or unmounting the component.
+```
+
+The default presentation is expanded on desktop and collapsed on mobile. Clicking a mobile link closes it. Titles are localized and omitted from their own entries. Use `title`, `maxLevel`, `desktopOpen`, `mobileOpen`, `mobileQuery`, or `render` to customize it. Styles are optional; see `toc.d.mts` for the complete interface.
+
+In Next.js, use this browser entry in a client component effect and return the cleanup function. Keep `syncContent` in build/server code. Both Vite and Next.js use the same package.
+
+## Release preparation
+
+See [RELEASING.md](RELEASING.md) for packaging checks, initial publication and OIDC setup.
+
+## JSON and HTML rendering
+
+```js
+import {renderArticleBody} from '@accelflow/space-content/render';
+const html = renderArticleBody(article.body, {
+  assets: content.assets, locale: 'ja', pdfMode: 'link',
+  renderers: {paragraph: ({children}) => `<p>${children}</p>`},
+});
+```
+
+Use this Node/build-time entry for both JSON (default) and legacy HTML. It renders
+headings, TOC, formatting, lists, tables, columns, links, images and attachment
+IDs, then sanitizes all output, including custom renderer output. Callbacks are
+trusted application code, never stored executable templates. Unknown nodes retain
+safe children. Dynamic smart links fall back to their label; supply a custom
+renderer for application-specific behavior. Use `resolveArticle` and
+`resolveSubArticles` for routes and child navigation.
+
+PDFs default to download links. `pdfMode: 'embed'` permits only local PDF paths
+listed in the manifest, with an empty sandbox and no referrer, plus a download
+link. Browser PDF viewers may not work in a sandbox; the link remains available.
+Arbitrary iframes, scripts, event handlers, inline styles, SVG and unsafe URLs
+are removed. JSON is not inherently trusted. The browser-only TOC module and its
+responsive CSS can be used unchanged with rendered JSON.
+
+Serve copied assets with their manifest MIME and `X-Content-Type-Options: nosniff`.
+Force Content-Disposition attachment for non-raster, non-PDF types (especially
+HTML/SVG); they must never execute at the site's origin. The examples emit those
+headers for Cloudflare-style hosts; configure equivalent rules on other hosts.

package/node.d.mts

@@ -0,0 +1,14 @@
+export interface BuildManifest {
+ version: 1; accountId: string; workspaceId: string; format: 'html'|'json'; snapshotId: string;
+ objects: Array<{hash:string;size:number}>;
+ articles: Array<{id:string;slug:string;title:string;metadataHash:string;bodyHash:string}>;
+ assets: Array<{id:string;hash:string;contentType:string;filename:string}>;
+}
+export interface SyncOptions {
+ apiUrl: string; downloadOrigin: string; accountId: string; workspaceId: string; token: string;
+ cacheDir: string; outputDir: string; fetch?: typeof globalThis.fetch; maxRetries?: number;
+}
+export function syncContent(options: SyncOptions): Promise<{
+ snapshotDir:string; manifest:BuildManifest;
+ diagnostics:{downloadedObjects:number;cacheHits:number};
+}>;

package/node.mjs

@@ -0,0 +1,200 @@
+import {createReadStream} from 'node:fs';
+import { createHash, randomUUID } from 'node:crypto';
+import { mkdir, readFile, writeFile, rename, rm, lstat, open, copyFile } from 'node:fs/promises';
+import { resolve, join } from 'node:path';
+const sha = bytes => createHash('sha256').update(bytes).digest('hex');
+const hashPattern = /^[a-f0-9]{64}$/;
+function validateManifest(m, accountId, workspaceId) {
+    if (m.version !== 1 || m.accountId !== accountId || m.workspaceId !== workspaceId || !['html', 'json'].includes(m.format) || !hashPattern.test(m.snapshotId) || !Array.isArray(m.objects) || m.objects.length > 4096 || !Array.isArray(m.articles) || !Array.isArray(m.assets))
+        throw Error('invalid_manifest');
+    const { snapshotId, ...fixed } = m;
+    if (sha(JSON.stringify(fixed)) !== snapshotId)
+        throw Error('manifest_checksum_mismatch');
+    const objects = new Map();
+    let total = 0;
+    for (const o of m.objects) {
+        if (!hashPattern.test(o.hash) || !Number.isSafeInteger(o.size) || o.size < 0 || o.size > 250_000_000 || objects.has(o.hash))
+            throw Error('invalid_manifest');
+        objects.set(o.hash, o);
+        total += o.size;
+    }
+    if (total > 1024 * 1024 * 1024)
+        throw Error('manifest_too_large');
+    for (const a of m.articles)
+        if (typeof a.id !== 'string' || typeof a.slug !== 'string' || typeof a.title !== 'string' || !objects.has(a.bodyHash) || !objects.has(a.metadataHash))
+            throw Error('invalid_manifest');
+    for (const a of m.assets)
+        if (typeof a.id !== 'string' || typeof a.contentType !== 'string' || typeof a.filename !== 'string' || /[\r\n\x00]/.test(a.filename) || !/^[a-z0-9!#$&^_.+-]+\/[a-z0-9!#$&^_.+-]+$/i.test(a.contentType) || !objects.has(a.hash))
+            throw Error('invalid_manifest');
+    return objects;
+}
+async function limitedText(response, max) {
+    const reader = response.body?.getReader();
+    if (!reader)
+        throw Error('missing_response');
+    const chunks = [];
+    let size = 0;
+    try {
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            size += value.length;
+            if (size > max)
+                throw Error('manifest_too_large');
+            chunks.push(Buffer.from(value));
+        }
+        return Buffer.concat(chunks).toString();
+    }
+    finally {
+        await reader.cancel().catch(() => { });
+    }
+}
+class Reader {
+    constructor(stream) { if (!stream)
+        throw Error('missing_stream'); this.reader = stream.getReader(); this.buffer = new Uint8Array(); }
+    async take(max) { if (!this.buffer.length) {
+        const r = await this.reader.read();
+        if (r.done)
+            return null;
+        this.buffer = r.value;
+    } const n = Math.min(max, this.buffer.length), v = this.buffer.subarray(0, n); this.buffer = this.buffer.subarray(n); return v; }
+    async line() { const chunks = []; for (let n = 0; n < 4096; n++) {
+        const b = await this.take(1);
+        if (!b)
+            throw Error('truncated_stream');
+        if (b[0] === 10)
+            return JSON.parse(Buffer.from(chunks).toString());
+        chunks.push(b[0]);
+    } throw Error('frame_too_large'); }
+}
+async function cacheValid(path,o) {
+ try {
+  const stat=await lstat(path);if(!stat.isFile()||stat.isSymbolicLink()||stat.size!==o.size)return false;
+  const digest=createHash('sha256');for await(const chunk of createReadStream(path))digest.update(chunk);
+  return digest.digest('hex')===o.hash;
+ }catch(e){if(e.code==='ENOENT')return false;throw e;}
+}
+async function cacheRead(path,o) {return await cacheValid(path,o)?readFile(path):null;}
+async function safeDirectory(path) { await mkdir(path, { recursive: true, mode: 0o700 }); const s = await lstat(path); if (s.isSymbolicLink() || !s.isDirectory())
+    throw Error('unsafe_cache_directory'); }
+/** Build-time only. cacheDir must be a private, trusted directory; never expose it to untrusted PRs. */
+export async function syncContent({ apiUrl, downloadOrigin, accountId, workspaceId, token, cacheDir, outputDir, fetch: fetcher = globalThis.fetch, maxRetries = 2 }) {
+    const api = new URL(apiUrl), allowed = new URL(downloadOrigin);
+    if (api.protocol !== 'https:' || allowed.protocol !== 'https:' || api.username || api.password || allowed.username || allowed.password)
+        throw Error('https_required');
+    if (!Number.isInteger(maxRetries) || maxRetries < 0 || maxRetries > 3)
+        throw Error('invalid_retry_limit');
+    const start = await fetcher(new URL(`/v1/build/accounts/${encodeURIComponent(accountId)}/workspaces/${encodeURIComponent(workspaceId)}/sessions`, api), { method: 'POST', headers: { Authorization: `Bearer ${token}` }, redirect: 'error', signal: AbortSignal.timeout(120000) });
+    if (!start.ok)
+        throw Error(`headless_session_${start.status}`);
+    const raw = await limitedText(start, 1100000);
+    const { session, manifest, downloadUrl, expiresAt } = JSON.parse(raw);
+    if (typeof session !== 'string' || session.length > 4096 || !Number.isFinite(expiresAt) || expiresAt <= Date.now())
+        throw Error('invalid_session');
+    const objects = validateManifest(manifest, accountId, workspaceId), url = new URL(downloadUrl);
+    if (url.origin !== allowed.origin || url.protocol !== 'https:' || url.username || url.password)
+        throw Error('untrusted_download_url');
+    const cache = resolve(cacheDir), output = resolve(outputDir);
+    if (output === cache || output.startsWith(cache + '/') || cache.startsWith(output + '/'))
+        throw Error('overlapping_directories');
+    await safeDirectory(cache);
+    const namespace = join(cache, sha(JSON.stringify([accountId, workspaceId, manifest.format, manifest.version])));
+    await safeDirectory(namespace);
+    const missing = [];
+    for (const o of objects.values())
+        if (!await cacheValid(join(namespace, o.hash), o))
+            missing.push(o.hash);
+    let pending = missing, downloads = 0;
+    for (let attempt = 0; pending.length; attempt++) {
+        if (attempt > maxRetries || Date.now() >= expiresAt)
+            throw Error('headless_transfer_incomplete');
+        let response;
+        try {
+            response = await fetcher(url, { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ session, hashes: pending }), redirect: 'error', signal: AbortSignal.timeout(Math.max(1, Math.min(1800000, expiresAt - Date.now()))) });
+        }
+        catch (error) {
+            if (attempt >= maxRetries)
+                throw error;
+            continue;
+        }
+        if ([429, 502, 503, 504].includes(response.status) && attempt < maxRetries) {
+            await response.body?.cancel();
+            await new Promise(resolve => setTimeout(resolve, Math.min(1000 * 2 ** attempt, 5000)));
+            continue;
+        }
+        if (!response.ok)
+            throw Error(`headless_download_${response.status}`);
+        const reader = new Reader(response.body);
+        let complete = false;
+        try {
+            const header = await reader.line();
+            if (header.version !== 1 || header.snapshotId !== manifest.snapshotId || header.count !== pending.length)
+                throw Error('invalid_stream_header');
+            const remaining = new Set(pending);
+            for (let i = 0; i < header.count; i++) {
+                const item = await reader.line(), expected = objects.get(item.hash);
+                if (!remaining.has(item.hash) || !expected || item.size !== expected.size)
+                    throw Error('unexpected_object');
+                const path=join(namespace,item.hash), temp=path+'.'+randomUUID()+'.partial';
+                const file=await open(temp,'wx',0o600), digest=createHash('sha256');
+                try {
+                    let received=0;
+                    while(received<item.size) {
+                        const chunk=await reader.take(item.size-received);
+                        if(!chunk)throw Error('truncated_stream');
+                        received+=chunk.length;digest.update(chunk);await file.writeFile(chunk);
+                    }
+                    if(digest.digest('hex')!==item.hash)throw Error('object_checksum_mismatch');
+                    await file.close();await rename(temp,path);
+                } finally {await file.close().catch(()=>{});await rm(temp,{force:true});}
+                remaining.delete(item.hash);
+                downloads++;
+            }
+            const end = await reader.line();
+            if (end.end !== true || end.snapshotId !== manifest.snapshotId || end.count !== header.count || await reader.take(1) !== null)
+                throw Error('invalid_stream_end');
+            complete = true;
+        }
+        catch (error) {
+            if (error.message !== 'truncated_stream' && !['TypeError', 'AbortError', 'TimeoutError'].includes(error.name) && error.message !== 'transfer_failed')
+                throw error;
+        }
+        finally {
+            await reader.reader.cancel().catch(() => { });
+        }
+        pending = [];
+        for (const o of missing.map(h => objects.get(h)))
+            if (!await cacheValid(join(namespace, o.hash), o))
+                pending.push(o.hash);
+        // A missing terminal marker is never accepted even when every object arrived.
+        if (!complete && !pending.length)
+            throw Error('missing_stream_end');
+    }
+    // Fresh generation, never merge with previous output (deleted articles/assets stay excluded).
+    await safeDirectory(output);
+    const generation = join(output, randomUUID());
+    await safeDirectory(generation);
+    try {
+        const articles = [];
+        for (const a of manifest.articles) {
+            const body = await cacheRead(join(namespace, a.bodyHash), objects.get(a.bodyHash)), metadata = await cacheRead(join(namespace, a.metadataHash), objects.get(a.metadataHash));
+            if (!body || !metadata)
+                throw Error('cache_corrupt');
+            articles.push({ ...a, metadata: JSON.parse(metadata), body: JSON.parse(body) });
+        }
+        await safeDirectory(join(generation, 'space-assets'));
+        for (const a of manifest.assets) {
+            const valid = await cacheValid(join(namespace, a.hash), objects.get(a.hash));
+            if (!valid)
+                throw Error('cache_corrupt');
+            await copyFile(join(namespace,a.hash),join(generation,'space-assets',a.hash));
+        }
+        await writeFile(join(generation, 'content.json'), JSON.stringify({ snapshotId: manifest.snapshotId, format: manifest.format, articles, assets: manifest.assets }));
+        return { snapshotDir: generation, manifest, diagnostics: { downloadedObjects: downloads, cacheHits: objects.size - missing.length } };
+    }
+    catch (e) {
+        await rm(generation, { recursive: true, force: true });
+        throw e;
+    }
+}

package/package.json

@@ -1,6 +1,56 @@
 {
   "name": "@accelflow/space-content",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0-beta.2",
+  "type": "module",
+  "engines": {
+    "node": ">=24"
+  },
+  "exports": {
+    "./node": {
+      "types": "./node.d.mts",
+      "import": "./node.mjs"
+    },
+    "./toc": {
+      "types": "./toc.d.mts",
+      "import": "./toc.mjs"
+    },
+    "./toc.css": "./toc.css",
+    "./render": {
+      "types": "./render.d.mts",
+      "import": "./render.mjs"
+    }
+  },
+  "scripts": {
+    "test": "node --test test/*.test.mjs",
+    "prepack": "npm test",
+    "verify:package": "node scripts/verify-package.mjs"
+  },
+  "files": [
+    "node.mjs",
+    "node.d.mts",
+    "README.md",
+    "toc.mjs",
+    "toc.d.mts",
+    "toc.css",
+    "LICENSE",
+    "render.mjs",
+    "render.d.mts"
+  ],
+  "description": "Build-time Headless CMS content sync and customizable table of contents for Accelflow Space",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Accelflow/space-content-sdk.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Accelflow/space-content-sdk/issues"
+  },
+  "homepage": "https://github.com/Accelflow/space-content-sdk#readme",
+  "publishConfig": {
+    "access": "public",
+    "tag": "beta"
+  },
+  "dependencies": {
+    "sanitize-html": "^2.18.0"
+  }
+}

package/render.d.mts

@@ -0,0 +1,11 @@
+export interface ContentNode { type: string; text?: string; attrs?: Record<string, unknown>; marks?: Array<{type:string;attrs?:Record<string,unknown>}>; content?: ContentNode[]; }
+export interface ContentAsset {id:string;hash:string;contentType:string;filename:string;}
+export interface RenderOptions {
+ assets?: ContentAsset[]; locale?: 'ja'|'en'; pdfMode?: 'link'|'embed';
+ renderers?: Record<string,(context:{node:ContentNode;children:string;defaultHtml:string;escapeHtml:typeof escapeHtml})=>string>;
+ resolveArticle?: (attrs:Record<string,unknown>)=>{href:string;title?:string}|undefined;
+ resolveSubArticles?: (attrs:Record<string,unknown>)=>Array<{href:string;title:string}>;
+}
+export function escapeHtml(value:unknown):string;
+export function sanitizeArticleHtml(html:string, options?:RenderOptions):string;
+export function renderArticleBody(body:ContentNode|string, options?:RenderOptions):string;

package/render.mjs

@@ -0,0 +1,95 @@
+import sanitizeHtml from 'sanitize-html';
+import {renderTableOfContents} from './toc.mjs';
+export const escapeHtml = value => String(value ?? '').replace(/[&<>"']/g, c => ({'&':'&amp;','<':'&lt;','>':'&gt;','"':'&quot;',"'":'&#39;'}[c]));
+const hash = /^[a-f0-9]{64}$/;
+const raster = new Set(['image/png','image/jpeg','image/gif','image/webp','image/avif']);
+function assetsIndex(assets = []) {
+ const ids = new Map(), paths = new Map();
+ for (const a of assets) {
+  if (!a || typeof a.id !== 'string' || !hash.test(a.hash) || typeof a.contentType !== 'string' || typeof a.filename !== 'string' || ids.has(a.id)) throw Error('invalid_render_asset');
+  ids.set(a.id,a); paths.set('/space-assets/'+a.hash,a);
+ }
+ return {ids,paths};
+}
+function safeUrl(value, image = false) {
+ if (typeof value !== 'string' || /[\u0000-\u0020\u007f\\]/.test(value)) return '';
+ if (/^(?:\/(?!\/)|#)/.test(value)) return value;
+ try {const u=new URL(value);return !u.username && !u.password && (image ? u.protocol==='https:' : ['https:','http:','mailto:','tel:'].includes(u.protocol)) ? value : '';} catch {return '';}
+}
+/** Build-time HTML sanitizer. Only known local PDF assets may be embedded, opt-in. */
+export function sanitizeArticleHtml(html, {assets = [], pdfMode = 'link'} = {}) {
+ if (typeof html !== 'string') throw Error('invalid_html_body');
+ const {paths}=assetsIndex(assets);
+ return sanitizeHtml(html, {
+  nonBooleanAttributes: sanitizeHtml.defaults.nonBooleanAttributes.filter(a=>a!=='sandbox'),
+  allowedTags: [...sanitizeHtml.defaults.allowedTags,'img','details','summary','nav',...(pdfMode==='embed'?['iframe']:[])],
+  allowedAttributes: {
+   '*':['id','class'], a:['href','title','data-level','download'],
+   img:['src','alt','title','width','height','loading','referrerpolicy'],
+   nav:['data-table-of-contents','data-max-level','aria-label'], details:['open','data-space-toc'],
+   li:['data-level','data-checked'], ol:['start'], td:['colspan','rowspan'], th:['colspan','rowspan','scope'],
+   iframe:['src','title','sandbox','loading','referrerpolicy'],
+  },
+  allowedClasses:{'*':['*']},
+  allowedSchemes:['https','http','mailto','tel'], allowedSchemesByTag:{img:['https'],iframe:[]}, allowProtocolRelative:false,
+  transformTags: {
+   iframe: (tagName, attrs) => ({tagName,attribs:{src:attrs.src??'',title:attrs.title??'PDF',sandbox:'',loading:'lazy',referrerpolicy:'no-referrer'}}),
+  },
+  exclusiveFilter: frame => frame.tag==='iframe' && !(pdfMode==='embed' && paths.get(frame.attribs.src)?.contentType==='application/pdf'),
+ });
+}
+/** Render Space's Tiptap JSON document. Custom callbacks are trusted code; their HTML is still sanitized. */
+export function renderArticleBody(body, options = {}) {
+ if (typeof body==='string') return sanitizeArticleHtml(body,options);
+ if (!body || body.type!=='doc' || !Array.isArray(body.content)) throw Error('invalid_document');
+ const {ids}=assetsIndex(options.assets), headings=[], anchors=new Map(), used=new Set();let count=0;
+ const text=n=>n.type==='text'?String(n.text??''):(n.content??[]).map(text).join('');
+ function inspect(n,depth=0) {
+  if (!n || typeof n!=='object' || typeof n.type!=='string' || ++count>100000 || depth>64 || (n.content!==undefined&&!Array.isArray(n.content))) throw Error('invalid_document');
+  for(const child of n.content??[])inspect(child,depth+1);
+ }
+ inspect(body);
+ function collect(n) {
+  if(n.type==='tableOfContents')return;
+  if(n.type==='heading') {const level=Number.isInteger(n.attrs?.level)&&n.attrs.level>=1&&n.attrs.level<=6?n.attrs.level:2;const title=text(n);let id=typeof n.attrs?.id==='string'&&/^[\p{L}\p{N}_-]+$/u.test(n.attrs.id)?n.attrs.id:title.toLowerCase().replace(/[^\p{L}\p{N}_-]+/gu,'-').replace(/^-|-$/g,'')||'heading';const base=id;let index=2;while(used.has(id))id=base+'-'+index++;used.add(id);anchors.set(n,id);headings.push({id,level,text:title});}
+  for(const child of n.content??[])collect(child);
+ }
+ collect(body);
+ const e=escapeHtml;
+ const wrap=(tag,children,attrs='')=>`<${tag}${attrs}>${children}</${tag}>`;
+ function render(n) {
+  const a=n.attrs??{}, children=(n.content??[]).map(render).join('');
+  let html='';
+  if(n.type==='text') {
+   html=e(n.text);
+   for(const mark of Array.isArray(n.marks)?n.marks:[]) {const tag={bold:'strong',italic:'em',underline:'u',strike:'s',code:'code'}[mark?.type];if(tag)html=wrap(tag,html);else if(mark?.type==='link'){const href=safeUrl(mark.attrs?.href);if(href)html=wrap('a',html,` href="${e(href)}"`);}}
+  } else if(n.type==='heading') html=wrap('h'+(Number.isInteger(a.level)&&a.level>=1&&a.level<=6?a.level:2),children,` id="${e(anchors.get(n))}"`);
+  else if(n.type==='tableOfContents') html=renderTableOfContents(headings,{locale:options.locale??'ja',maxLevel:a.maxLevel===2?2:3});
+  else if(n.type==='image') {const src=safeUrl(a.src,true);html=src?`<img src="${e(src)}" alt="${e(a.alt)}" loading="lazy" referrerpolicy="no-referrer">`:'';}
+  else if(n.type==='attachment') {
+   const asset=ids.get(a.attachmentId);if(!asset)throw Error('attachment_not_in_manifest');
+   const src='/space-assets/'+asset.hash, label=e(asset.filename);
+   html=raster.has(asset.contentType)?`<img src="${src}" alt="${label}" loading="lazy">`:`<a href="${src}" download="${label}">${label}</a>`;
+   if(asset.contentType==='application/pdf'&&options.pdfMode==='embed')html=`<iframe class="space-pdf" src="${src}" title="${label}" sandbox="" loading="lazy" referrerpolicy="no-referrer"></iframe>`+html;
+  } else if(n.type==='externalLinkCard') {const href=safeUrl(a.href);html=href?wrap('a',e(a.title||href),` href="${e(href)}"`):e(a.title);}
+  else if(n.type==='articleReference') {const target=options.resolveArticle?.(a);const href=safeUrl(target?.href);const label=e(a.labelMode==='custom'?a.customLabel:target?.title??a.fallbackTitle??a.title??'');html=href?wrap('a',label,` href="${e(href)}"`):label;}
+  else if(n.type==='smartLink') html=e(a.label??a.categoryLabel??'');
+  else if(n.type==='subArticleList') html=wrap('nav',wrap('ol',(options.resolveSubArticles?.(a)??[]).map(x=>{const href=safeUrl(x.href);return href?wrap('li',wrap('a',e(x.title),` href="${e(href)}"`)):'';}).join('')));
+  else if(n.type==='hardBreak')html='<br>';
+  else if(n.type==='horizontalRule')html='<hr>';
+  else if(n.type==='codeBlock')html=wrap('pre',wrap('code',e(text(n)),` class="language-${e(String(a.language??'text').replace(/[^\w-]/g,''))}"`));
+  else if(n.type==='columnLayout')html=wrap('div',children,' class="space-columns"');
+  else if(n.type==='column')html=wrap('div',children,' class="space-column"');
+  else {
+   const tag={doc:null,paragraph:'p',bulletList:'ul',orderedList:'ol',listItem:'li',taskList:'ul',taskItem:'li',blockquote:'blockquote',table:'table',tableRow:'tr',tableCell:'td',tableHeader:'th'}[n.type];
+   let attrs='';
+   if(n.type==='orderedList'&&Number.isSafeInteger(a.start)&&a.start>0)attrs=` start="${a.start}"`;
+   if(n.type==='taskItem')attrs=` class="space-task" data-checked="${a.checked===true}"`;
+   if(['tableCell','tableHeader'].includes(n.type))for(const key of ['colspan','rowspan'])if(Number.isInteger(a[key])&&a[key]>0&&a[key]<=100)attrs+=` ${key}="${a[key]}"`;
+   html=tag?wrap(tag,children,attrs):children;
+  }
+  const custom=Object.hasOwn(options.renderers??{},n.type)?options.renderers[n.type]:null;
+  return custom?custom({node:n,children,defaultHtml:html,escapeHtml:e}):html;
+ }
+ return sanitizeArticleHtml(render(body),options);
+}

package/toc.css

@@ -0,0 +1,22 @@
+/* Optional marketing-derived responsive theme. Override variables or omit this file. */
+.space-toc { margin: 36px 0 42px; border: 1px solid var(--space-toc-border, #d9e5d8); border-radius: 0; padding: 24px 28px; background: var(--space-toc-background, #f5f9f0); }
+[data-space-toc] > summary { display: flex; align-items: center; justify-content: space-between; margin: 0 0 14px; color: var(--space-toc-color, #26352b); cursor: pointer; font-family: Manrope, sans-serif; font-size: 18px; font-weight: 700; list-style: none; }
+[data-space-toc] > summary::-webkit-details-marker { display: none; }
+[data-space-toc] > summary::after { content: "−"; margin-left: 20px; font-size: 22px; font-weight: 500; line-height: 1; }
+.space-toc:not([open]) { padding-block: 5px; }
+.space-toc:not([open]) > summary { margin-bottom: 0; }
+.space-toc:not([open]) > summary::after { content: "+"; }
+.space-toc ol { display: grid; gap: 8px; margin: 0; padding: 0; list-style: none; counter-reset: blog-toc-h2; }
+.space-toc li { margin: 0; line-height: 1.45; }
+.space-toc li[data-level="2"] { display: grid; grid-template-columns: 1.5em minmax(0, 1fr); column-gap: .45em; align-items: baseline; counter-increment: blog-toc-h2; }
+.space-toc li[data-level="2"]::before { content: counter(blog-toc-h2) ". "; color: #74836f; font-weight: 700; text-align: right; }
+.space-toc li[data-level="3"] { padding-left: 1.25em; font-size: .94em; }
+.space-toc a { color: var(--space-toc-link, #405f31); text-decoration: none; }
+.space-toc a:hover { color: #65a511; text-decoration: underline; }
+@media (max-width: 620px) {
+  .space-toc { position: sticky; top: calc(var(--space-toc-header-height, 64px) + 12px); z-index: 10; padding: 20px; }
+  .space-toc.is-stuck:not([open]) { width: 44px; height: 44px; margin-left: auto; padding: 0; background: #fff; border-radius: 50%; box-shadow: 0 4px 16px rgba(0, 0, 0, .14); }
+  .space-toc.is-stuck:not([open]) > summary { width: 42px; height: 42px; justify-content: center; margin: 0; font-size: 0; }
+  .space-toc.is-stuck:not([open]) > summary::before { content: ""; display: block; flex: 0 0 20px; width: 20px; height: 20px; background: currentColor; -webkit-mask: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24'%3E%3Cpath d='M3 5h2v2H3zM7 5h14v2H7zM3 11h2v2H3zM7 11h14v2H7zM3 17h2v2H3zM7 17h14v2H7z'/%3E%3C/svg%3E") center / contain no-repeat; mask: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24'%3E%3Cpath d='M3 5h2v2H3zM7 5h14v2H7zM3 11h2v2H3zM7 11h14v2H7zM3 17h2v2H3zM7 17h14v2H7z'/%3E%3C/svg%3E") center / contain no-repeat; }
+  .space-toc.is-stuck:not([open]) > summary::after { content: none; margin: 0; }
+}

package/toc.d.mts

@@ -0,0 +1,10 @@
+export type TocHeading = {id: string; text: string; level: number};
+export type TocOptions = {
+  locale?: 'ja' | 'en'; title?: string; maxLevel?: 2 | 3; className?: string;
+  /** Trusted application renderer; escape data if returning custom HTML. */
+  render?: (data: {title: string; entries: (TocHeading & {href: string})[]}) => string;
+  mobileQuery?: string; mobileOpen?: boolean; desktopOpen?: boolean;
+};
+export function isTocTitle(text: string): boolean;
+export function renderTableOfContents(headings: TocHeading[], options?: TocOptions): string;
+export function mountTableOfContents(root: HTMLElement, options?: TocOptions): () => void;

package/toc.mjs

@@ -0,0 +1,52 @@
+/** Framework-independent TOC presentation. Pass trusted CMS HTML to the host
+ * renderer; this module only creates text/fragment links, never executes content. */
+const escape = value => String(value).replace(/[&<>"']/g, c => ({'&':'&amp;','<':'&lt;','>':'&gt;','"':'&quot;',"'":'&#39;'}[c]));
+export const isTocTitle = text => /^(?:目次|table\s+of\s+contents)$/i.test(String(text).replace(/[【】［］\[\]]/g, '').trim());
+export function renderTableOfContents(headings, {locale = 'ja', title = locale === 'en' ? 'Table of contents' : '目次', maxLevel = 3, className = '', render} = {}) {
+  const entries = headings.filter(h => h.level >= 2 && h.level <= maxLevel && h.text.trim() && !isTocTitle(h.text)).map(h => ({...h, href: '#' + encodeURIComponent(h.id)}));
+  if (render) return render({title, entries});
+  return `<details class="space-toc ${escape(className)}" data-space-toc open><summary>${escape(title)}</summary><ol>${entries.map(h => `<li data-level="${h.level}"><a href="${escape(h.href)}">${escape(h.text)}</a></li>`).join('')}</ol></details>`;
+}
+/** Upgrade CMS nav blocks and install responsive behavior. Returns cleanup for
+ * React effects / client navigation. Custom render output must use data-space-toc
+ * on a details element to opt into the standard behavior. */
+export function mountTableOfContents(root, options = {}) {
+  const win = root.ownerDocument.defaultView;
+  const originals = [];
+  for (const nav of root.querySelectorAll('nav[data-table-of-contents]')) {
+    const headings = [...nav.querySelectorAll('a[href^="#"]')].map(a => {
+      const fragment = a.getAttribute('href').slice(1);
+      let id; try { id = decodeURIComponent(fragment); } catch { id = fragment; }
+      return {id, text: a.textContent ?? '', level: Number(a.dataset.level ?? 2)};
+    });
+    const template = root.ownerDocument.createElement('template');
+    template.innerHTML = renderTableOfContents(headings, {maxLevel: Number(nav.dataset.maxLevel) === 2 ? 2 : 3, ...options});
+    const nodes = [...template.content.childNodes];
+    nav.replaceWith(...nodes); originals.push({nav, nodes});
+  }
+  const tocs = [...root.querySelectorAll('details[data-space-toc]')];
+  const media = win.matchMedia(options.mobileQuery ?? '(max-width: 620px)');
+  let frame = null;
+  const sticky = () => {
+    if (frame !== null) return;
+    frame = win.requestAnimationFrame(() => {
+      frame = null;
+      for (const toc of tocs) {
+        const top = parseFloat(win.getComputedStyle(toc).top) || 0;
+        toc.classList.toggle('is-stuck', media.matches && toc.getBoundingClientRect().top <= top + 1);
+      }
+    });
+  };
+  const sync = () => { for (const toc of tocs) toc.open = media.matches ? (options.mobileOpen ?? false) : (options.desktopOpen ?? true); sticky(); };
+  const click = e => {
+    const link = e.target.closest?.('a[href^="#"]');
+    const toc = link?.closest('details[data-space-toc]');
+    if (toc && root.contains(toc) && media.matches) { toc.open = false; sticky(); }
+  };
+  sync(); media.addEventListener('change', sync); win.addEventListener('scroll', sticky, {passive:true}); root.addEventListener('click', click);
+  return () => {
+    media.removeEventListener('change', sync); win.removeEventListener('scroll', sticky); root.removeEventListener('click', click);
+    if (frame !== null) win.cancelAnimationFrame(frame);
+    for (const {nav, nodes} of originals) { if (nodes[0]?.parentNode) nodes[0].before(nav); for (const node of nodes) node.remove(); }
+  };
+}