@accelflow/space-content 0.1.0-beta.1 → 0.1.0-beta.3

package/README.md

@@ -1,8 +1,8 @@
-# Space build content SDK (unpublished)
+# Space build content SDK
 
 Node 24+ build-time content synchronization for Space Headless CMS, with optional browser-safe table-of-contents presentation. Licensed under MIT.
 
-The initial npm release is being prepared; the commands below apply once it is published.
+The beta package is available on npm.
 
 ```sh
 npm install @accelflow/space-content@beta
@@ -49,12 +49,16 @@ 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.
 
-Current limits: 4,096 unique objects per batch, 64 MiB per object, 1 GiB total;
-API publication adapter additionally limits assets to 16 MiB each. Retry count
-is bounded (default 2). Larger manifest sharding, partial-object resume,
-framework-specific adapters, cache GC and npm publication are follow-up work.
+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 test` from this repository root (no dependencies required).
+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.
 
@@ -82,3 +86,124 @@ In Next.js, use this browser entry in a client component effect and return the c
 ## 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.
+
+## Author profile pages (Vite / Next.js)
+
+`@accelflow/space-content/profile` is a framework-independent, token-free entrypoint.
+It generates the author biography, site introduction, organization/publisher and
+published article list from the metadata received by `syncContent()`. It also
+provides `ProfilePage` JSON-LD. Requires Space's profile metadata publication support.
+Old snapshots without author metadata must supply `identity` explicitly; no company
+or author is silently invented. An explicit identity also supports a zero-article page.
+
+```js
+import {createAuthorProfile, renderAuthorProfile} from '@accelflow/space-content/profile';
+import '@accelflow/space-content/profile.css';
+
+const profile = createAuthorProfile(content.articles, {
+  origin: 'https://your-site.example',
+  locale: 'ja',
+  url: '/ja/blog/authors/editorial-team/',
+  articleHref: article => `/ja/blog/${article.slug}/`,
+});
+const html = renderAuthorProfile(profile, {
+  labels: {about: '編集部について', articles: '編集部の記事'},
+});
+```
+
+Run this on the build/server side after syncing. `html` is a page fragment: place it
+inside your layout, with a UTF-8 charset, viewport, page title, description and canonical
+URL. Vite must prerender it (see the example); Next.js can use it in a statically
+exported server page. Use `profile.author`, `siteIntroduction`, `publisher`, `articles`
+and `jsonLd` to build your own React components instead of using the standard HTML.
+Do not pass API tokens into the profile object or browser bundles.
+
+The optional CSS is responsive and has `--space-profile-width`, `--space-profile-color`,
+`--space-profile-font`, `--space-profile-border`, and `--space-profile-link` overrides.
+You may omit it entirely. Labels can be overridden with `about`, `company`, `articles`,
+`empty`; `includeStructuredData: false` lets your framework own JSON-LD insertion.
+Content is treated as text, not executable HTML. Only HTTP(S) links are accepted;
+unsafe custom article routes fail the build. JSON-LD escapes `<` against script breakout.
+Language overrides use `translations.ja/en`, falling back per field to common values.
+Draft articles, other locales and articles with a different author are excluded.
+
+### CMS URL and link targets
+
+When a Space workspace has a CMS URL, the delivery API rewrites article links
+before returning HTML or JSON. Use the article base URL (for example,
+`https://example.com/ja/blog/`). Workspace references use that base plus the
+published page-tree path. Links with the same hostname become root-relative;
+other HTTP(S) links retain an absolute URL and carry `target="_blank"` with
+`rel="noopener noreferrer"`. The renderer preserves these safe external targets.
+Fragments, email and telephone links retain their normal behavior. Consumers
+with custom renderers should honor these link attributes. An empty CMS URL
+retains existing API link behavior. Update the build after changing the URL.
+
+### Heading IDs and table-of-contents links
+
+TOC links percent-encode the heading ID once (for example, `#%E3%81%BE%E3%81%A8%E3%82%81`).
+Valid explicit heading IDs are preserved. To retain an existing site's generation
+rules for headings without IDs, pass `headingId` to `renderArticleBody`:
+
+```js
+renderArticleBody(body, {
+  headingId: text => text.replace(/<[^>]+>/g, '').trim().toLowerCase()
+    .replace(/[\s/]+/g, '-').replace(/[^\p{Letter}\p{Number}-]/gu, '')
+    .replace(/-{2,}/g, '-') || 'heading',
+});
+```
+
+Return an unencoded ID containing only Unicode letters, numbers, `_` or `-`.
+Explicit IDs take priority over generated IDs; collisions receive numeric suffixes.
+Without the option, the SDK's existing generation rules remain unchanged.
+
+### Paragraph spacing in tables and lists
+
+Import the optional body stylesheet after your site's typography CSS and add
+`space-content` to the element containing the rendered article:
+
+```js
+import '@accelflow/space-content/content.css';
+```
+```html
+<article class="space-content">…sanitized article HTML…</article>
+```
+
+Single paragraphs directly inside table cells or list items have no outside
+margin. Consecutive paragraphs keep a `0.5em` gap. Empty paragraphs retain a line
+of height; `<br>`, nested lists and paragraph nodes are not removed. Other
+paragraphs and content outside this wrapper are unchanged. Customize the gap:
+
+```css
+.space-content { --space-content-paragraph-gap: 0.75em; }
+```

package/content.css

@@ -0,0 +1,11 @@
+/* Opt-in article body layout. Keep paragraphs and intentional empty lines intact. */
+.space-content :where(td, th, li) > p {
+  margin-block: 0;
+}
+.space-content :where(td, th, li) > p + p {
+  margin-block-start: var(--space-content-paragraph-gap, 0.5em);
+}
+.space-content :where(td, th, li) > p:empty {
+  min-block-size: 1em;
+  min-block-size: 1lh;
+}

package/node.mjs

@@ -1,5 +1,6 @@
+import {createReadStream} from 'node:fs';
 import { createHash, randomUUID } from 'node:crypto';
-import { mkdir, readFile, writeFile, rename, rm, lstat } from 'node:fs/promises';
+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}$/;
@@ -12,7 +13,7 @@ function validateManifest(m, accountId, workspaceId) {
     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 > 64 * 1024 * 1024 || objects.has(o.hash))
+        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;
@@ -23,7 +24,7 @@ function validateManifest(m, accountId, workspaceId) {
         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' || !objects.has(a.hash))
+        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;
 }
@@ -67,24 +68,14 @@ class Reader {
         chunks.push(b[0]);
     } throw Error('frame_too_large'); }
 }
-async function cacheRead(path, o) { try {
-    if (!(await lstat(path)).isFile() || (await lstat(path)).isSymbolicLink())
-        return null;
-    const b = await readFile(path);
-    return b.length === o.size && sha(b) === o.hash ? b : null;
+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;}
 }
-catch (e) {
-    if (e.code === 'ENOENT')
-        return null;
-    throw e;
-} }
-async function save(path, data) { const temp = path + '.' + randomUUID() + '.partial'; try {
-    await writeFile(temp, data, { flag: 'wx', mode: 0o600 });
-    await rename(temp, path);
-}
-finally {
-    await rm(temp, { force: true });
-} }
+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. */
@@ -112,7 +103,7 @@ export async function syncContent({ apiUrl, downloadOrigin, accountId, workspace
     await safeDirectory(namespace);
     const missing = [];
     for (const o of objects.values())
-        if (!await cacheRead(join(namespace, o.hash), o))
+        if (!await cacheValid(join(namespace, o.hash), o))
             missing.push(o.hash);
     let pending = missing, downloads = 0;
     for (let attempt = 0; pending.length; attempt++) {
@@ -145,18 +136,18 @@ export async function syncContent({ apiUrl, downloadOrigin, accountId, workspace
                 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 data = Buffer.alloc(item.size);
-                let offset = 0;
-                while (offset < data.length) {
-                    const chunk = await reader.take(data.length - offset);
-                    if (!chunk)
-                        throw Error('truncated_stream');
-                    data.set(chunk, offset);
-                    offset += chunk.length;
-                }
-                if (sha(data) !== item.hash)
-                    throw Error('object_checksum_mismatch');
-                await save(join(namespace, item.hash), data);
+                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++;
             }
@@ -174,7 +165,7 @@ export async function syncContent({ apiUrl, downloadOrigin, accountId, workspace
         }
         pending = [];
         for (const o of missing.map(h => objects.get(h)))
-            if (!await cacheRead(join(namespace, o.hash), o))
+            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)
@@ -194,10 +185,10 @@ export async function syncContent({ apiUrl, downloadOrigin, accountId, workspace
         }
         await safeDirectory(join(generation, 'space-assets'));
         for (const a of manifest.assets) {
-            const data = await cacheRead(join(namespace, a.hash), objects.get(a.hash));
-            if (!data)
+            const valid = await cacheValid(join(namespace, a.hash), objects.get(a.hash));
+            if (!valid)
                 throw Error('cache_corrupt');
-            await writeFile(join(generation, 'space-assets', a.hash), data);
+            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 } };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@accelflow/space-content",
-  "version": "0.1.0-beta.1",
+  "version": "0.1.0-beta.3",
   "type": "module",
   "engines": {
     "node": ">=24"
@@ -14,7 +14,17 @@
       "types": "./toc.d.mts",
       "import": "./toc.mjs"
     },
-    "./toc.css": "./toc.css"
+    "./toc.css": "./toc.css",
+    "./render": {
+      "types": "./render.d.mts",
+      "import": "./render.mjs"
+    },
+    "./profile": {
+      "types": "./profile.d.mts",
+      "import": "./profile.mjs"
+    },
+    "./profile.css": "./profile.css",
+    "./content.css": "./content.css"
   },
   "scripts": {
     "test": "node --test test/*.test.mjs",
@@ -28,7 +38,13 @@
     "toc.mjs",
     "toc.d.mts",
     "toc.css",
-    "LICENSE"
+    "LICENSE",
+    "render.mjs",
+    "render.d.mts",
+    "profile.mjs",
+    "profile.d.mts",
+    "profile.css",
+    "content.css"
   ],
   "description": "Build-time Headless CMS content sync and customizable table of contents for Accelflow Space",
   "license": "MIT",
@@ -43,5 +59,8 @@
   "publishConfig": {
     "access": "public",
     "tag": "beta"
+  },
+  "dependencies": {
+    "sanitize-html": "^2.18.0"
   }
 }

package/profile.css

@@ -0,0 +1,9 @@
+/* Optional marketing-inspired theme. Override custom properties or use your own CSS. */
+.space-profile{max-width:var(--space-profile-width,960px);margin:0 auto;padding:clamp(24px,5vw,64px) 24px;color:var(--space-profile-color,#17332a);font-family:var(--space-profile-font,system-ui,sans-serif);line-height:1.8;overflow-wrap:anywhere}
+.space-profile header{padding-bottom:40px;border-bottom:1px solid var(--space-profile-border,#dce4e0)}
+.space-profile h1{font-size:clamp(28px,4vw,48px);line-height:1.3;font-weight:600}
+.space-profile h2{font-size:clamp(22px,3vw,30px);line-height:1.4;margin:0 0 20px}
+.space-profile section{margin-top:48px}.space-profile p{margin:0 0 20px}.space-profile-text{white-space:pre-line}
+.space-profile-eyebrow{font-size:14px;font-weight:700}.space-profile a{color:var(--space-profile-link,#237568);text-underline-offset:4px}
+.space-profile-logo{max-width:180px;max-height:72px;object-fit:contain;margin-bottom:16px}.space-profile li{margin:12px 0}
+@media(max-width:620px){.space-profile{padding:24px 20px}.space-profile section{margin-top:32px}.space-profile header{padding-bottom:24px}}

package/profile.d.mts

@@ -0,0 +1,7 @@
+export type ProfileParty = {name:string;url?:string;type?:'Person'|'Organization';id?:string;logo?:string;description?:string;organizationName?:string;organizationUrl?:string;translations?:Partial<Record<'ja'|'en',Partial<Pick<ProfileParty,'name'|'url'|'description'|'organizationName'|'organizationUrl'>>>>};
+export type SiteIntroduction = {heading:string;body:string;translations?:Partial<Record<'ja'|'en',Partial<{heading:string;body:string}>>>};
+export type ProfileIdentity = {author?:ProfileParty;publisher?:ProfileParty;siteIntroduction?:SiteIntroduction};
+export type ProfileArticle = {id?:string;slug:string;title:string;metadata?:Record<string,unknown>;[key:string]:unknown};
+export type AuthorProfile = {locale:'ja'|'en';url:string;author:ProfileParty;publisher?:ProfileParty;siteIntroduction?:{heading:string;body:string};articles:{id:string;title:string;url:string}[];jsonLd:Record<string,unknown>};
+export function createAuthorProfile(articles:ProfileArticle[],options:{origin:string;locale?:'ja'|'en';identity?:ProfileIdentity;url?:string;articleHref?:(article:ProfileArticle)=>string}):AuthorProfile;
+export function renderAuthorProfile(profile:AuthorProfile,options?:{labels?:Partial<Record<'about'|'company'|'articles'|'empty',string>>;includeStructuredData?:boolean}):string;

package/profile.mjs

@@ -0,0 +1,56 @@
+const escape = value => String(value ?? '').replace(/[&<>"']/g, c => ({'&':'&amp;','<':'&lt;','>':'&gt;','"':'&quot;',"'":'&#39;'}[c]));
+function url(value, origin) {
+ if (typeof value !== 'string' || /[\u0000-\u0020\u007f\\]/.test(value) || value.startsWith('//')) return '';
+ try {const u=new URL(value,origin);return ['http:','https:'].includes(u.protocol)&&!u.username&&!u.password ? u.href : '';} catch {return '';}
+}
+function party(value, locale) {
+ if (!value || typeof value!=='object') return undefined;
+ const p={...value};
+ for(const key of ['name','url','description','organizationName','organizationUrl']) if(typeof value.translations?.[locale]?.[key]==='string')p[key]=value.translations[locale][key];
+ if(typeof p.name!=='string'||!p.name.trim())return undefined;
+ return {name:p.name,type:p.type==='Person'?'Person':'Organization',url:url(p.url),id:url(p.id),logo:url(p.logo),description:typeof p.description==='string'?p.description:'',organizationName:typeof p.organizationName==='string'?p.organizationName:'',organizationUrl:url(p.organizationUrl)};
+}
+function schemaParty(p) {
+ return {'@type':p.type,name:p.name,...(p.url?{url:p.url}:{}),...(p.id?{'@id':p.id}:{}),...(p.logo?{logo:p.logo}:{}),...(p.description?{description:p.description}:{})};
+}
+const sameAuthor=(a,b)=> (a.id&&b.id)?a.id===b.id:(a.url&&b.url)?a.url===b.url:a.name===b.name;
+/** Build a profile view model from published SDK articles. Does not fetch or access tokens. */
+export function createAuthorProfile(articles, options) {
+ const {origin,locale='ja',identity,articleHref}=options??{};
+ if(!['ja','en'].includes(locale))throw Error('invalid_profile_locale');
+ const base=url(origin);if(!base)throw Error('invalid_profile_origin');
+ const candidates=articles.filter(a=>(a.metadata?.locale??a.locale??'ja')===locale && (a.metadata??a).draft!==true);
+ const metadata=identity??candidates.find(a=>(a.metadata??a).author)?.metadata??candidates.find(a=>a.author)??{};
+ const author=party(metadata.author,locale);if(!author)throw Error('profile_author_required');
+ const publisher=party(metadata.publisher,locale);
+ const source=metadata.siteIntroduction;
+ const intro=source?{...source,...source.translations?.[locale]}:undefined;
+ const siteIntroduction=intro&&typeof intro.heading==='string'&&typeof intro.body==='string'?{heading:intro.heading,body:intro.body}:undefined;
+ const canonicalUrl=url(options.url??author.url,base);if(!canonicalUrl)throw Error('invalid_profile_url');
+ const list=candidates.filter(a=>{const p=party((a.metadata??a).author,locale);return !p||sameAuthor(p,author);}).map(a=>{
+  let href;
+  if(articleHref)href=url(articleHref(a),base);
+  else {
+   const raw=(a.metadata??a).path??'/'+a.slug;
+   if(typeof raw!=='string'||!/^\/(?!\/)/.test(raw)||raw.slice(1).split('/').some(s=>!/^[-_\p{L}\p{N}]+$/u.test(s)))throw Error('invalid_profile_article_path');
+   href=url('/articles/'+raw.slice(1).split('/').map(encodeURIComponent).join('/')+'/',base);
+  }
+  if(!href)throw Error('invalid_profile_article_url');
+  return {id:a.id??a.slug,title:String(a.title??''),url:href};
+ });
+ const entity=schemaParty(author);
+ if(author.organizationName)entity[author.type==='Person'?'affiliation':'parentOrganization']={...(publisher&&publisher.url===author.organizationUrl?schemaParty(publisher):{'@type':'Organization'}),name:author.organizationName,...(author.organizationUrl?{url:author.organizationUrl}:{})};
+ const jsonLd={'@context':'https://schema.org','@type':'ProfilePage','@id':canonicalUrl+'#profile',url:canonicalUrl,name:author.name,description:author.description,inLanguage:locale==='ja'?'ja-JP':'en-US',mainEntity:entity,...(publisher?{publisher:schemaParty(publisher)}:{})};
+ return {locale,url:canonicalUrl,author,publisher,siteIntroduction,articles:list,jsonLd};
+}
+/** Safe default HTML. Customize labels/CSS or render the view model in React instead. */
+export function renderAuthorProfile(profile,{labels={},includeStructuredData=true}={}) {
+ const ja=profile.locale==='ja';
+ const text={about:ja?'プロフィール':'Profile',company:ja?'運営会社':'Published by',articles:ja?'記事一覧':'Articles',empty:ja?'公開中の記事はまだありません。':'There are no published articles yet.',...labels};
+ const a=profile.author,p=profile.publisher;
+ const link=(href,label)=>url(href)?`<a href="${escape(url(href))}">${escape(label)}</a>`:escape(label);
+ const logo=p?.logo&&url(p.logo)?`<img class="space-profile-logo" src="${escape(url(p.logo))}" alt="${escape(p.name)}" loading="lazy" referrerpolicy="no-referrer">`:'';
+ const company=a.organizationName||p?.name;
+ const data=includeStructuredData?`<script type="application/ld+json">${JSON.stringify(profile.jsonLd).replaceAll('<','\\u003c')}</script>`:'';
+ return `${data}<article class="space-profile" lang="${ja?'ja':'en'}"><header><p class="space-profile-eyebrow">${escape(text.about)}</p><h1>${escape(a.name)}</h1><p class="space-profile-text">${escape(a.description)}</p></header>${profile.siteIntroduction?`<section><h2>${escape(profile.siteIntroduction.heading)}</h2><p class="space-profile-text">${escape(profile.siteIntroduction.body)}</p></section>`:''}${company?`<section><h2>${escape(text.company)}</h2>${logo}<p>${link(a.organizationUrl||p?.url,company)}</p></section>`:''}<section><h2>${escape(text.articles)}</h2>${profile.articles.length?`<ul>${profile.articles.map(item=>`<li>${link(item.url,item.title)}</li>`).join('')}</ul>`:`<p>${escape(text.empty)}</p>`}</section></article>`;
+}

package/render.d.mts

@@ -0,0 +1,13 @@
+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 {
+ /** Used only when a heading has no valid explicit ID. Return an unencoded ID. */
+ headingId?: (text:string)=>string;
+ 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,99 @@
+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 linkTarget = attrs => attrs?.target === '_blank' ? ' target="_blank" rel="noopener noreferrer"' : '';
+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','target','rel'],
+   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: {
+   a: (tagName, attrs) => {const {target,rel,...rest}=attrs;return {tagName,attribs:{...rest,...(target==='_blank'&&/^https?:\/\//i.test(safeUrl(attrs.href))?{target:'_blank',rel:'noopener noreferrer'}:{})}};},
+   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(), reserved=new Set();let count=0;
+ const validId=id=>typeof id==='string' && /^[\p{L}\p{N}_-]+$/u.test(id);
+ 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');
+  if(n.type==='heading' && validId(n.attrs?.id))reserved.add(n.attrs.id);
+  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);const explicit=validId(n.attrs?.id);let id=explicit?n.attrs.id:options.headingId?options.headingId(title):title.toLowerCase().replace(/[^\p{L}\p{N}_-]+/gu,'-').replace(/^-|-$/g,'')||'heading';if(!validId(id))throw Error('invalid_heading_id');const base=id;let index=2;while(used.has(id)||(!explicit&&reserved.has(id))||(id!==base&&reserved.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)}"${linkTarget(mark.attrs)}`);}}
+  } 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)}"${linkTarget(a)}`):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);
+}