@flood-md/agent 0.2.9 → 0.2.11

package/lib/index.mjs

@@ -0,0 +1,144 @@
+import { readFile, lstat, realpath, open } from 'node:fs/promises';
+import { createHash } from 'node:crypto';
+import { dirname, resolve, relative, isAbsolute, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const DEFAULT_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const KINDS = new Set(['guide', 'workflow', 'reference', 'component', 'recipe', 'token']);
+const ID = /^[a-z][a-z0-9-]*:[a-z0-9][a-z0-9.-]*$/;
+const MAX_CATALOG_BYTES = 8 * 1024 * 1024;
+const MAX_MATERIAL_BYTES = 1024 * 1024;
+const PAGE_BYTES = 16 * 1024;
+const digest = bytes => createHash('sha256').update(bytes).digest('hex');
+const fail = (code, message) => { const error = new Error(message); error.code = code; throw error; };
+const inside = (root, path) => { const r = relative(root, path); return r === '' || (r !== '..' && !r.startsWith('..' + sep) && !isAbsolute(r)); };
+const safePath = path => typeof path === 'string' && /^[a-zA-Z0-9._/-]+$/.test(path) && !path.startsWith('/') && !path.split('/').some(part => !part || part === '.' || part === '..');
+const text = (value, limit) => typeof value === 'string' && value.trim().length > 0 && value.length <= limit;
+
+/** Validate the data contract without loading material bodies or executing instructions. */
+export function validateKnowledgeCatalog(catalog) {
+  if (catalog?.schemaVersion !== 1 || !/^\d+\.\d+\.\d+$/.test(catalog.version ?? '') || !Array.isArray(catalog.groups) || !catalog.groups.length || catalog.groups.length > 16 || !Array.isArray(catalog.materials) || !catalog.materials.length || !Array.isArray(catalog.capabilities) || catalog.capabilities.length > 32) fail('INVALID_CATALOG', 'Unsupported or incomplete Flood knowledge catalog.');
+  const groups = new Set(), ids = new Set(), files = new Set();
+  for (const group of catalog.groups) {
+    if (!/^[a-z][a-z0-9-]*$/.test(group.id ?? '') || groups.has(group.id) || !text(group.name, 128) || !text(group.description, 256)) fail('INVALID_CATALOG', 'Invalid or duplicate knowledge group.');
+    groups.add(group.id);
+  }
+  let previous = '';
+  for (const item of catalog.materials) {
+    if (!ID.test(item.id ?? '') || ids.has(item.id) || item.id <= previous || !KINDS.has(item.kind) || !item.id.startsWith(item.kind + ':') || !text(item.name, 128) || !text(item.description, 1024) || !safePath(item.file) || files.has(item.file) || !/^[a-f0-9]{64}$/.test(item.sha256 ?? '') || !Number.isSafeInteger(item.bytes) || item.bytes < 1 || item.bytes > MAX_MATERIAL_BYTES || !Array.isArray(item.groups) || !item.groups.length || item.groups.length > 8 || new Set(item.groups).size !== item.groups.length || item.groups.some(group => !groups.has(group)) || !Array.isArray(item.links) || !Array.isArray(item.requires) || item.status !== 'available') fail('INVALID_CATALOG', 'Invalid, unsorted or duplicate knowledge material.');
+    if (item.installedTarget !== undefined && (!safePath(item.installedTarget) || !(item.installedTarget.startsWith('flood/') || item.installedTarget.startsWith('.agents/skills/flood-ui/')))) fail('INVALID_CATALOG', 'Invalid owned guide target.');
+    if (item.requires.length > 16 || item.links.length > 256 || new Set(item.requires).size !== item.requires.length || new Set(item.links).size !== item.links.length) fail('INVALID_CATALOG', 'Knowledge relationships exceed their per-material budget or contain duplicates.');
+    ids.add(item.id); files.add(item.file); previous = item.id;
+  }
+  const byId = new Map(catalog.materials.map(item => [item.id, item]));
+  for (const item of catalog.materials) for (const id of [...item.links, ...item.requires]) if (!ids.has(id)) fail('INVALID_CATALOG', `Unresolved knowledge relationship: ${id}`);
+  const visiting = new Set(), depths = new Map();
+  const visit = id => {
+    if (visiting.has(id)) fail('INVALID_CATALOG', 'Knowledge prerequisite cycle.');
+    if (depths.has(id)) return depths.get(id);
+    if (visiting.size >= 32) fail('INVALID_CATALOG', 'Knowledge prerequisites exceed the supported depth.');
+    visiting.add(id);
+    let depth = 1;
+    for (const dependency of byId.get(id).requires) depth = Math.max(depth, 1 + visit(dependency));
+    visiting.delete(id);
+    if (depth > 32) fail('INVALID_CATALOG', 'Knowledge prerequisites exceed the supported depth.');
+    depths.set(id, depth); return depth;
+  };
+  for (const id of ids) visit(id);
+  const capabilities = new Set();
+  for (const item of catalog.capabilities) {
+    if (!/^[a-z][a-z0-9-]*$/.test(item.id ?? '') || capabilities.has(item.id) || !['available', 'not-provided'].includes(item.status) || !text(item.description, 256) || !Array.isArray(item.materials) || item.materials.length > 16 || item.materials.some(id => !ids.has(id)) || (item.status === 'available' && !item.materials.length) || (item.status === 'not-provided' && item.materials.length)) fail('INVALID_CATALOG', 'Invalid knowledge capability declaration.');
+    capabilities.add(item.id);
+  }
+  return catalog;
+}
+
+async function readRegular(root, path, maxBytes) {
+  if (!safePath(path)) fail('INVALID_PATH', 'Knowledge paths must come from the package catalog.');
+  const base = await realpath(root);
+  let current = base;
+  for (const part of path.split('/')) {
+    current = resolve(current, part);
+    const stat = await lstat(current).catch(() => fail('MISSING_MATERIAL', `Missing knowledge file: ${path}`));
+    if (stat.isSymbolicLink()) fail('INVALID_PATH', 'Refusing a linked knowledge file or directory.');
+  }
+  if (!inside(base, await realpath(current))) fail('INVALID_PATH', 'Knowledge file left its package root.');
+  const handle = await open(current, 'r');
+  try {
+    const stat = await handle.stat();
+    if (!stat.isFile() || stat.nlink !== 1 || stat.size > maxBytes) fail('INVALID_MATERIAL', 'Knowledge file is not a bounded regular file.');
+    const bytes = await handle.readFile();
+    if (bytes.length > maxBytes) fail('INVALID_MATERIAL', 'Knowledge file exceeds its read budget.');
+    return bytes;
+  } finally { await handle.close(); }
+}
+
+const decode = bytes => { try { return new TextDecoder('utf-8', { fatal: true }).decode(bytes); } catch { fail('INVALID_MATERIAL', 'Knowledge must be valid UTF-8.'); } };
+const summary = ({id, kind, name, description, groups, status, links, requires}) => ({id, kind, name, description, groups: [...groups], status, relatedCount: links.length, requires: [...requires]});
+
+/** A provider-neutral, read-only reader. A fresh catalog is checked on every operation. */
+export function createKnowledgeReader({root = DEFAULT_ROOT} = {}) {
+  async function load() {
+    const bytes = await readRegular(root, 'dist/catalog.json', MAX_CATALOG_BYTES);
+    let catalog;
+    try { catalog = JSON.parse(decode(bytes)); } catch (error) { if (error.code) throw error; fail('INVALID_CATALOG', 'Malformed Flood knowledge catalog.'); }
+    validateKnowledgeCatalog(catalog);
+    const pkg = JSON.parse(decode(await readRegular(root, 'package.json', 64 * 1024)));
+    if (pkg.name !== '@flood-md/agent' || pkg.version !== catalog.version) fail('VERSION_MISMATCH', 'Agent package and knowledge catalog versions differ.');
+    return {catalog, fingerprint: digest(bytes)};
+  }
+  return {
+    async info() {
+      const {catalog, fingerprint} = await load();
+      return {schemaVersion: 1, version: catalog.version, fingerprint, materialCount: catalog.materials.length,
+        groups: catalog.groups.map(group => ({...group, count: catalog.materials.filter(item => item.groups.includes(group.id)).length})),
+        kinds: [...KINDS].map(kind => ({kind, count: catalog.materials.filter(item => item.kind === kind).length})),
+        capabilities: structuredClone(catalog.capabilities)};
+    },
+    async list({kind, group, search = '', limit = 12, cursor} = {}) {
+      if ((kind !== undefined && !KINDS.has(kind)) || !Number.isSafeInteger(limit) || limit < 1 || limit > 50 || typeof search !== 'string' || search.length > 160) fail('INVALID_QUERY', 'Invalid catalog kind, limit or search.');
+      const {catalog, fingerprint} = await load();
+      if (group !== undefined && !catalog.groups.some(item => item.id === group)) fail('INVALID_QUERY', 'Unknown knowledge group.');
+      const query = {kind: kind ?? null, group: group ?? null, search: search.trim().toLowerCase()};
+      const queryHash = digest(JSON.stringify(query));
+      let offset = 0;
+      if (cursor !== undefined) {
+        let state;
+        try { if (typeof cursor !== 'string' || cursor.length > 1024 || !/^[A-Za-z0-9_-]+$/.test(cursor)) throw Error(); state = JSON.parse(Buffer.from(cursor, 'base64url').toString('utf8')); } catch { fail('INVALID_CURSOR', 'Malformed knowledge cursor.'); }
+        if (state.fingerprint !== fingerprint || state.query !== queryHash || !Number.isSafeInteger(state.offset) || state.offset < 1) fail('STALE_CURSOR', 'Catalog or query changed; start a fresh catalog page.');
+        offset = state.offset;
+      }
+      const matches = catalog.materials.filter(item => (!kind || item.kind === kind) && (!group || item.groups.includes(group)) && (!query.search || `${item.id} ${item.name} ${item.description}`.toLowerCase().includes(query.search)));
+      if (offset > matches.length) fail('INVALID_CURSOR', 'Knowledge cursor is outside the result set.');
+      const page = [];
+      const response = () => {
+        const next = offset + page.length;
+        return {schemaVersion: 1, version: catalog.version, fingerprint, query, total: matches.length, items: page,
+          truncated: next < matches.length, nextCursor: next < matches.length ? Buffer.from(JSON.stringify({fingerprint, query: queryHash, offset: next})).toString('base64url') : null};
+      };
+      for (const item of matches.slice(offset, offset + limit)) {
+        page.push(summary(item));
+        if (Buffer.byteLength(JSON.stringify(response())) > PAGE_BYTES) { page.pop(); break; }
+      }
+      if (offset < matches.length && !page.length) fail('INVALID_CATALOG', 'A catalog entry exceeds the discovery budget.');
+      return response();
+    },
+    async read(id, {offset = 0, length = 10000, linksOffset = 0} = {}) {
+      if (!ID.test(id ?? '') || !Number.isSafeInteger(offset) || offset < 0 || !Number.isSafeInteger(length) || length < 1 || length > 40000 || !Number.isSafeInteger(linksOffset) || linksOffset < 0) fail('INVALID_QUERY', 'Use a known material ID and a bounded character range.');
+      const {catalog, fingerprint} = await load();
+      const item = catalog.materials.find(item => item.id === id);
+      if (!item) fail('UNKNOWN_MATERIAL', `Unknown installed knowledge material: ${id}`);
+      if (linksOffset > item.links.length) fail('INVALID_QUERY', 'Link offset is outside the material.');
+      const bytes = await readRegular(root, item.file, MAX_MATERIAL_BYTES);
+      if (bytes.length !== item.bytes || digest(bytes) !== item.sha256) fail('INTEGRITY_MISMATCH', 'Knowledge content differs from the versioned catalog.');
+      const chars = Array.from(decode(bytes));
+      if (offset > chars.length) fail('INVALID_QUERY', 'Read offset is outside the material.');
+      const end = Math.min(chars.length, offset + length);
+      return {schemaVersion: 1, version: catalog.version, fingerprint, ...summary(item), source: 'package',
+        sha256: item.sha256, installedTarget: item.installedTarget ?? null, links: item.links.slice(linksOffset, linksOffset + 32),
+        linksOffset, nextLinksOffset: linksOffset + 32 < item.links.length ? linksOffset + 32 : null,
+        text: chars.slice(offset, end).join(''), offset, totalCharacters: chars.length,
+        truncated: end < chars.length, nextOffset: end < chars.length ? end : null};
+    },
+  };
+}

package/lib/inspect.d.ts

@@ -0,0 +1,12 @@
+export interface InspectionTarget {tag:string;id:string|null;className:string;label:string;}
+export interface InspectionIssue {id:'icons.text-glyph'|'icons.unslotted-svg'|'table.mixed-row-centre'|'table.word-fragment'|'copy.action-echo'|'copy.unowned-support'|'forms.track-drift'|'forms.content-track-drift'|'layout.page-overflow';target:InspectionTarget;related?:InspectionTarget;message:string;offset?:number;word?:string;}
+export interface RenderedUIInspection {
+  schemaVersion:1;issues:InspectionIssue[];copy:InspectionTarget[];
+  fields:(InspectionTarget&{x:number;y:number;width:number;height:number})[];
+  truncated:boolean;notChecked:string[];
+}
+/** Invoke inside a browser document, e.g. page.evaluate(inspectRenderedUI). No mutation or network calls. */
+export declare function inspectRenderedUI(options?:{rootSelector?:string;maxElements?:number}):RenderedUIInspection;
+export interface SourceUIIssue {id:'composition.native-dialog'|'composition.native-control'|'composition.layout-owner'|'composition.scaled-minimum';line:number;column:number;excerpt:string;owner:string;message:string;}
+/** Text observations, not an AST or conformance check. No file access, execution or network. */
+export declare function inspectSourceUI(source:string,options?:{format?:'jsx'|'css';maxFindings?:number}):{schemaVersion:1;issues:SourceUIIssue[];truncated:boolean;notChecked:string[]};

package/lib/inspect.mjs

@@ -0,0 +1,187 @@
+/** Optional text observations for host-owned JSX/CSS; no parsing or execution. */
+export function inspectSourceUI(source,options={}) {
+  if(typeof source!=='string'||source.length>500000)throw new Error('Source must be a string of at most 500000 UTF-16 units');
+  const limit=options.maxFindings??50,format=options.format??'jsx';
+  if(!Number.isSafeInteger(limit)||limit<1||limit>500)throw new Error('maxFindings must be an integer from 1 to 500');
+  if(!['jsx','css'].includes(format))throw new Error('format must be jsx or css');
+  const issues=[];let truncated=false;
+  const record=(match,id,owner,message)=>{
+    if(issues.length>=limit){truncated=true;return;}
+    const offset=match.index+match[0].length-match[0].trimStart().length;
+    const prefix=source.slice(0,offset),line=prefix.split('\n').length,column=offset-prefix.lastIndexOf('\n');
+    issues.push({id,line,column,excerpt:match[0].trimStart().slice(0,180),owner,message});
+  };
+  if(format==='jsx'){
+    for(const match of source.matchAll(/\b(?:window|globalThis)\.(confirm|alert|prompt)\s*\(/g))record(match,'composition.native-dialog',match[1]==='confirm'?'AlertDialog':match[1]==='prompt'?'Dialog':'Alert','Native browser dialog candidate. Review the actual call and use the installed Flood owner unless native UI is explicitly required.');
+    for(const match of source.matchAll(/<(select|button)\b|<input\b[^>]*\btype\s*=\s*["'](date|time|checkbox|radio|range)["']/g)){
+      const role=match[1]||match[2],owner={select:'Select',button:'Button',date:'DatePicker',time:'TimeField',checkbox:'Checkbox',radio:'Radio',range:'Slider'}[role];
+      record(match,'composition.native-control',owner,'Raw control candidate. Review whether an existing Flood component owns this role; native form/table structure and deliberate documented adapters are separate cases.');
+    }
+  } else {
+    for(const match of source.matchAll(/([^{}]+)\{[^{}]*\bdisplay\s*:\s*(grid|flex)\b/g)){
+      if(match[1].trim().startsWith('.flood-'))continue;
+      record(match,'composition.layout-owner',match[2]==='grid'?'Grid':'Stack / Inline','Custom layout candidate. Shared form tracks and repeated layout roles should use Flood owners. A semantic host shell can legitimately own positioning; record the actual reason.');
+    }
+    for(const match of source.matchAll(/\bmin-(?:width|inline-size)\s*:\s*(\d*\.?\d+)rem\b/g)){
+      if(Number(match[1])>0)record(match,'composition.scaled-minimum','Container / local ScrollArea','Rem-based minimum width candidate. If applied to the whole host, it can force page overflow when text grows. Dense table minima can be legitimate inside a local scroll owner; inspect the actual selector and enlarged desktop result.');
+    }
+  }
+  return {schemaVersion:1,issues,truncated,notChecked:['Text matching is not parsing: comments, strings and examples can match; aliases, dynamic types and indirect calls can be missed. Review source context.','This function reads only the supplied text. It does not execute it, open files or inspect imports, component capability, rendered layout or editorial necessity.']};
+}
+
+/** Read-only DOM observations. Pass this self-contained function to page.evaluate. */
+export function inspectRenderedUI(options = {}) {
+  if (typeof document === 'undefined') throw new Error('inspectRenderedUI must run in the rendered browser document');
+  const root = options.rootSelector ? document.querySelector(options.rootSelector) : document;
+  if (!root) throw new Error('Flood inspection root was not found');
+  const limit = options.maxElements ?? 500;
+  if (!Number.isSafeInteger(limit) || limit < 1 || limit > 2000) throw new Error('maxElements must be an integer from 1 to 2000');
+  const issues = [], copy = [], fields = [];
+  const visible = element => {
+    const style = getComputedStyle(element), box = element.getBoundingClientRect();
+    return style.display !== 'none' && style.visibility !== 'hidden' && box.width > 0 && box.height > 0;
+  };
+  const label = element => (element.getAttribute('aria-label') || element.textContent || '').trim().replace(/\s+/g, ' ').slice(0, 180);
+  const target = element => ({tag:element.tagName.toLowerCase(), id:element.id || null, className:element.getAttribute('class') || '', label:label(element)});
+  let truncated = false;
+  const addIssue = finding => { if (issues.length < limit) issues.push(finding); else truncated = true; };
+  const select = selector => {
+    const matches = [...root.querySelectorAll(selector)].filter(visible);
+    if(matches.length > limit) truncated = true;
+    return matches.slice(0, limit);
+  };
+  if(root===document&&document.documentElement.scrollWidth>innerWidth+1)addIssue({id:'layout.page-overflow',target:{tag:'html',id:document.documentElement.id||null,className:document.documentElement.getAttribute('class')||'',label:'Document'},offset:document.documentElement.scrollWidth-innerWidth,message:'The document extends beyond the viewport. Review the actual overflow owner at this text size; dense content can scroll locally. Hiding page overflow does not repair the layout.'});
+  for (const button of select('button.flood-button, button.flood-icon-button')) {
+    // Text is inspected outside real icon slots, SVGs and visually hidden names.
+    const walker = document.createTreeWalker(button, NodeFilter.SHOW_TEXT);
+    const parts = []; let node;
+    while ((node = walker.nextNode())) {
+      if (!node.parentElement?.closest('.flood-icon,svg,.flood-visually-hidden,[aria-hidden="true"]')) parts.push(node.textContent);
+    }
+    const text = parts.join('').trim();
+    if (/^[+＋×✕✖↗→←✓✔☰](?:\s|$)|(?:\s)[+＋×✕✖↗→←✓✔☰]$/u.test(text)) {
+      addIssue({id:'icons.text-glyph', target:target(button), message:'Possible action icon encoded as font text; review whether IconSlot with explicit artwork is required.'});
+    }
+    for (const svg of button.querySelectorAll('svg')) {
+      if (!svg.closest('.flood-icon,.flood-loading,.flood-spinner')) addIssue({id:'icons.unslotted-svg',target:target(button),message:'Action SVG has no Flood IconSlot owner; inspect sizing and accessible decoration.'});
+    }
+  }
+  for (const row of select('.flood-table tbody tr')) {
+    const controls = [...row.querySelectorAll('input:not([type="hidden"]),textarea,select')].filter(visible);
+    const actions = [...row.querySelectorAll('button,a.flood-link--button')].filter(visible);
+    if (!controls.length && !actions.length) continue;
+    const centres = controls.map(control=>{const r=control.getBoundingClientRect();return r.y+r.height/2;});
+    if (centres.length && Math.max(...centres)-Math.min(...centres)>3) continue;
+    const rowBox=row.getBoundingClientRect();
+    const expected = centres.length ? centres.reduce((a,b)=>a+b,0)/centres.length : rowBox.y+rowBox.height/2;
+    for (const cell of row.children) {
+      if(!cell.matches('td,th') || !visible(cell)) continue;
+      // Editable rows compare their passive content to input centres. Record/action
+      // rows compare every complete content block, including multiline identities.
+      if(centres.length && cell.querySelector('input,textarea,select')) continue;
+      const boxes=[];
+      const walker=document.createTreeWalker(cell,NodeFilter.SHOW_TEXT);let textNode;
+      while((textNode=walker.nextNode())) {
+        if(!textNode.textContent?.trim() || !textNode.parentElement || !visible(textNode.parentElement)
+          || textNode.parentElement.closest('.flood-visually-hidden,[aria-hidden="true"],script,style')) continue;
+        const range=document.createRange();range.selectNodeContents(textNode);
+        boxes.push(...[...range.getClientRects()].filter(rect=>rect.width>0&&rect.height>0));
+      }
+      for(const control of [...cell.querySelectorAll('button,a.flood-link--button')].filter(visible)) boxes.push(control.getBoundingClientRect());
+      if(!boxes.length) continue;
+      const actual=(Math.min(...boxes.map(rect=>rect.top))+Math.max(...boxes.map(rect=>rect.bottom)))/2;
+      if(Math.abs(actual-expected)>3) addIssue({id:'table.mixed-row-centre',target:target(cell),offset:Math.round((actual-expected)*100)/100,message:centres.length
+        ? 'Cell content is offset from neighbouring input centres. Review resolved geometry.'
+        : 'Cell content is offset from the centre of a record/action row. Compare multiline identity, values and actions; use deliberate top alignment only when justified.'});
+    }
+  }
+  const actionNames=select('button.flood-button,a.flood-link--button').map(button=>(button.textContent||'').trim().replace(/\s+/g,' ').toLowerCase()).filter(name=>name.length>=4);
+  let wordsChecked=0;
+  const segmenters=new Map();
+  const canInspectWords=typeof Intl.Segmenter==='function';
+  if(canInspectWords)for(const cell of select('.flood-table th,.flood-table td')){
+    if(cell.matches('[data-wrap="anywhere"]'))continue;
+    const locale=cell.closest('[lang]')?.getAttribute('lang')||document.documentElement.lang||undefined;
+    if(!segmenters.has(locale)){
+      try{segmenters.set(locale,new Intl.Segmenter(locale,{granularity:'word'}));}
+      catch{segmenters.set(locale,new Intl.Segmenter(undefined,{granularity:'word'}));}
+    }
+    const walker=document.createTreeWalker(cell,NodeFilter.SHOW_TEXT);let node;
+    while((node=walker.nextNode())){
+      if(!node.parentElement||!visible(node.parentElement)||node.parentElement.closest('code,pre,.flood-inline-code,.flood-visually-hidden,[aria-hidden="true"]'))continue;
+      for(const word of segmenters.get(locale).segment(node.textContent||'')){
+        if(!word.isWordLike||word.segment.length<4)continue;
+        if(wordsChecked>=limit){truncated=true;break;}wordsChecked++;
+        if(word.segment.length>200)continue;
+        const range=document.createRange();range.setStart(node,word.index);range.setEnd(node,word.index+word.segment.length);
+        const boxes=[...range.getClientRects()].filter(rect=>rect.width>0&&rect.height>0);
+        if(boxes.length>1&&Math.max(...boxes.map(rect=>rect.y))-Math.min(...boxes.map(rect=>rect.y))>2){
+          addIssue({id:'table.word-fragment',target:target(cell),word:word.segment,message:'A word is split across rendered lines in a table cell. Review intrinsic column width and wrapping; deliberate technical or localized line breaking can be an exception.'});
+        }
+      }
+      if(wordsChecked>=limit)break;
+    }
+    if(wordsChecked>=limit){truncated=true;break;}
+  }
+  const grids=select('form [class]').filter(element=>{
+    if(element.closest('table') || getComputedStyle(element).display!=='grid')return false;
+    return [...element.children].filter(visible).length>=2 && element.querySelectorAll('input,select,textarea,[role="combobox"]').length>=2;
+  }).map(element=>{
+    const style=getComputedStyle(element),columns=style.gridTemplateColumns.match(/[\d.]+px/g)?.map(parseFloat)??[];
+    return {element,columns,gap:parseFloat(style.columnGap)||0,rect:element.getBoundingClientRect()};
+  }).filter(grid=>grid.columns.length>=2);
+  const contentTracks=grid=>{
+    const owners='.flood-field,.flood-date-picker,.flood-date-field,.flood-time-field,.flood-date-range-field,.flood-date-time-picker';
+    const nodes=[...grid.element.querySelectorAll(owners)].filter(element=>visible(element)&&!element.closest('table')&&!element.parentElement?.closest(owners));
+    if(nodes.length>limit)truncated=true;
+    const tracks=[];
+    for(const element of nodes.slice(0,limit)){
+      const rect=element.getBoundingClientRect();
+      const track=tracks.find(item=>Math.abs(item.x-rect.x)<=1);
+      if(track){if(Math.abs(track.width-rect.width)>1)return null;}
+      else tracks.push({x:rect.x,width:rect.width});
+    }
+    if(tracks.length!==grid.columns.length)return null;
+    tracks.sort((a,b)=>a.x-b.x);
+    return {tracks,left:tracks[0].x,right:Math.max(...tracks.map(track=>track.x+track.width))};
+  };
+  for(const grid of grids)grid.content=contentTracks(grid);
+  for(let i=0;i<grids.length;i++)for(let j=i+1;j<grids.length;j++){
+    const a=grids[i],b=grids[j];
+    if(a.element.closest('form')!==b.element.closest('form'))continue;
+    if(a.element.contains(b.element)||b.element.contains(a.element))continue;
+    if(!(a.rect.bottom<=b.rect.top+1||b.rect.bottom<=a.rect.top+1))continue;
+    if(a.content&&b.content&&a.content.tracks.length===b.content.tracks.length&&Math.abs(a.content.left-b.content.left)<=1&&Math.abs(a.content.right-b.content.right)<=1){
+      const offset=Math.max(...a.content.tracks.map((track,index)=>Math.max(Math.abs(track.x-b.content.tracks[index].x),Math.abs(track.width-b.content.tracks[index].width))));
+      if(offset>1)addIssue({id:'forms.content-track-drift',target:target(b.element),related:target(a.element),offset:Math.round(offset*100)/100,message:'Stacked form groups share content edges but their actual field starts or widths differ. Review nested surface padding and shared track ownership; matching Grid props or outer boxes is insufficient.'});
+    }
+    if(Math.abs(a.rect.x-b.rect.x)>1||Math.abs(a.rect.width-b.rect.width)>1)continue;
+    const starts=grid=>grid.columns.map((_,index)=>grid.columns.slice(0,index).reduce((sum,width)=>sum+width,0)+index*grid.gap);
+    const left=starts(a),right=starts(b);
+    const drift=a.columns.length===b.columns.length?Math.max(...left.map((x,index)=>Math.abs(x-right[index]))):null;
+    if(drift===null||drift>1)addIssue({id:'forms.track-drift',target:target(b.element),related:target(a.element),...(drift===null?{}:{offset:Math.round(drift*100)/100}),message:'Stacked form grids share an outer frame but use different tracks. Review common gutters/group hierarchy or document why these contexts need different columns.'});
+  }
+  for(const element of select('h1,h2,h3,h4,h5,h6,.flood-type--helper,.flood-type--compact')) {
+    if(label(element)) {
+      copy.push(target(element));
+      if(!element.closest('button,a,label') && !element.matches('h1,h2,h3,h4,h5,h6')) {
+        if(!element.closest('.flood-field,.flood-fieldset,.flood-table,.flood-metric,.flood-status-indicator,.flood-file-meta,.flood-description-list,nav,article,dialog,[role="document"],[role="status"],[role="alert"],[role="alertdialog"],[role="dialog"]')) {
+          addIssue({id:'copy.unowned-support',target:target(element),message:'Supporting text sits outside a field, operation state, navigation or structured document. Identify the exact current decision it serves; remove implementation narration. Do not change typography or add a semantic wrapper merely to silence this observation.'});
+        }
+        const text=(element.textContent||'').trim().replace(/\s+/g,' ').toLowerCase();
+        if(actionNames.some(name=>text.includes(name))) addIssue({id:'copy.action-echo',target:target(element),message:'Supporting copy repeats a currently visible action label. Review whether it adds a necessary constraint or only narrates the control.'});
+      }
+    }
+  }
+  for(const element of select('.flood-field,fieldset,.flood-section')) {
+    const rect=element.getBoundingClientRect();
+    fields.push({...target(element),x:rect.x,y:rect.y,width:rect.width,height:rect.height});
+  }
+  return {schemaVersion:1, issues, copy, fields, truncated, notChecked:[
+    'Editorial necessity and accuracy require contextual review; copy inventory is not an editorial verdict.',
+    'Form grouping and column hierarchy require review of task relationships and visible geometry.',
+    'Only the currently rendered document state is inspected; portals outside a selected root, other pages, iframes and shadow roots are not traversed.',
+    'These observations do not certify accessibility, functional correctness or overall visual quality.',
+    ...(!canInspectWords?['Word fragmentation was not inspected because Intl.Segmenter is unavailable.']:[])
+  ]};
+}

package/manifest.json

@@ -2,6 +2,11 @@
   "schemaVersion": 1,
   "entry": "SKILL.md",
   "files": [
+    {
+      "source": "dist/catalog.json",
+      "target": "flood/catalog.json",
+      "kind": "catalog"
+    },
     {
       "source": "DESIGN.md",
       "target": "flood/DESIGN.md",
@@ -67,6 +72,11 @@
       "target": ".agents/skills/flood-ui/references/flood-spacing/SKILL.md",
       "kind": "skill"
     },
+    {
+      "source": "references/flood-motion/SKILL.md",
+      "target": ".agents/skills/flood-ui/references/flood-motion/SKILL.md",
+      "kind": "skill"
+    },
     {
       "source": "references/flood-foundations/SKILL.md",
       "target": ".agents/skills/flood-ui/references/flood-foundations/SKILL.md",
@@ -106,9 +116,49 @@
       "source": "references/flood-verification/SKILL.md",
       "target": ".agents/skills/flood-ui/references/flood-verification/SKILL.md",
       "kind": "skill"
+    },
+    {
+      "source": "references/knowledge.md",
+      "target": ".agents/skills/flood-ui/references/knowledge.md",
+      "kind": "reference"
+    },
+    {
+      "source": "references/flood-interface-content/SKILL.md",
+      "target": ".agents/skills/flood-ui/references/flood-interface-content/SKILL.md",
+      "kind": "skill"
+    },
+    {
+      "source": "references/interface-content-examples.md",
+      "target": ".agents/skills/flood-ui/references/interface-content-examples.md",
+      "kind": "reference"
+    },
+    {
+      "source": "references/rendered-review.md",
+      "target": ".agents/skills/flood-ui/references/rendered-review.md",
+      "kind": "reference"
+    },
+    {
+      "source": "references/flood-hierarchy/SKILL.md",
+      "target": ".agents/skills/flood-ui/references/flood-hierarchy/SKILL.md",
+      "kind": "skill"
+    },
+    {
+      "source": "references/flood-records/SKILL.md",
+      "target": ".agents/skills/flood-ui/references/flood-records/SKILL.md",
+      "kind": "skill"
+    },
+    {
+      "source": "references/record-decisions.md",
+      "target": ".agents/skills/flood-ui/references/record-decisions.md",
+      "kind": "reference"
+    },
+    {
+      "source": "references/component-families.md",
+      "target": ".agents/skills/flood-ui/references/component-families.md",
+      "kind": "reference"
     }
   ],
-  "version": "0.2.9",
+  "version": "0.2.11",
   "installedEntry": ".agents/skills/flood-ui/SKILL.md",
   "pathBase": "source is package-relative; target is relative to the host project root"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flood-md/agent",
-  "version": "0.2.9",
+  "version": "0.2.11",
   "type": "module",
   "description": "Versioned Flood design instructions for coding agents.",
   "license": "MIT",
@@ -13,12 +13,24 @@
     "DESIGN.md",
     "SKILL.md",
     "references",
+    "lib",
+    "dist",
+    "knowledge.json",
     "workflows.json",
     "rules.json",
     "manifest.json",
     "README.md"
   ],
   "exports": {
+    "./inspect": {
+      "types": "./lib/inspect.d.ts",
+      "import": "./lib/inspect.mjs"
+    },
+    ".": {
+      "types": "./lib/index.d.ts",
+      "import": "./lib/index.mjs"
+    },
+    "./dist/*": "./dist/*",
     "./DESIGN.md": "./DESIGN.md",
     "./SKILL.md": "./SKILL.md",
     "./manifest.json": "./manifest.json",

package/references/component-families.md

@@ -0,0 +1,146 @@
+# Author a component that belongs to Flood
+
+Use when adding a reusable primitive, extending its visual contract or composing
+a new shared component. This applies inside Flood itself and to project-owned
+composites. Keep the installed/source distinction: a consumer cannot invent a new
+package export or edit an installed dependency to implement these decisions.
+
+## Choose the family before choosing values
+
+Identify the component's role and compare the closest existing owners in their
+rendered states. A new name is not a reason for a new visual recipe. Record the
+chosen siblings and intentional differences in development notes, outside the UI.
+
+| Relationship | What should be shared |
+| --- | --- |
+| Action and icon action | Button/IconButton height, text, icon scale, insets and focus treatment |
+| Text/selection/number field | Field label relationship, control height and field-state semantics |
+| Command collection | Toolbar/Menu owners, action sizes and keyboard ownership |
+| Floating surface | Existing overlay material, layer placement, inset and focus restoration |
+| Named content or record | Typography, hierarchy and metadata owners, not a new title scale |
+
+Reuse these owners inside the new component. Extend the smallest missing owner
+before adding a composite override. For example, the Toolbar that draws an
+OverflowActions background owns its shape; a playground-only border-radius does
+not establish that capability for other consumers.
+
+## Define the visual and behavioral contract together
+
+- Use matching semantic token roles. Equal-looking values are not necessarily
+  interchangeable roles; a field radius and an action radius can evolve separately.
+- Derive sizes from the family's controls. Label line height, explicit icon box,
+  interactive height and optical insets must still agree at every exposed size.
+- Name variants by a meaningful role or shape. Keep appearance separate from
+  state: selected, read-only, disabled, invalid and focus are not interchangeable.
+- Make the outer geometry deliberate. A single-row capsule action rail can use
+  a pill shape; a wrapping or vertical group may need rounded geometry. Do not
+  blindly apply a pill to a multi-row surface. Use the spacing workflow to assess
+  nested radii and the actual inset; independently interactive neighbours need
+  not share a concentric-radius formula.
+- Account for padding and stroke in the space available to children. Overflow
+  calculations use the content box, not the outer border rectangle. Check the
+  threshold at which an item moves into the overflow owner.
+- Keep behaviour in the component that owns it. A focusable read-only text field
+  still needs a visible focus indicator and selection/copy. It blocks edits and
+  its chooser; disabled has a different native contract. Do not erase focus to
+  make a state look quieter or add helper copy merely to explain that contract.
+
+## Compare the family in one scene
+
+Repeated navigation/record rows share columns, not just height and font. Before
+accepting a composition, compare glyph centers, label starts and trailing action
+centers between header, groups, iconless/icon-bearing rows and footer. Define the
+indent of descendants deliberately and reserve missing peer anatomy. Scrollbar
+visibility must not silently change only the middle pane's content tracks.
+
+NavigationItem owns shared row geometry for native Link destinations, Button
+commands and disclosure. A branch without a destination uses a full-row toggle;
+a destination with children has distinct sibling link and disclosure targets,
+never nested controls or a link click that also toggles. The complete row owns
+its current/hover surface, so selection does not end at an unrelated shorter pill
+before the chevron. Budget real trailing anatomy once. NavigationTree composes
+these rows and manages hierarchy rather than supplying a parallel visual recipe.
+
+NavigationGroup owns optional label/action/separator and independent group
+disclosure. Its compact presentation reveals destinations without discarding the
+accepted expanded choice. Hiding a title cannot remove a needed accessible name
+or make a command unreachable. Compare headed/unheaded groups and all optional
+anatomy; an available slot is not a reason to populate it.
+
+Sidebar reuses NavigationGroup and NavigationTree. Its compact branches reuse
+Popover; full destinations retain Link and normal Tab behavior. Header/footer
+adapt through slots, with opt-in shell separators. The actual brand, toggle,
+destination and account hit areas share the full compact rail axis; a centered
+wrapper around a start-aligned Menu trigger is insufficient. Expanded slots share
+icon/text tracks. Its ScrollArea uses the existing edge lane for clearance. Keep
+material at the sidebar owner, without another material behind each group.
+Separate route identity, group/branch expansion and sidebar width; compare both
+profiles beside the small owners at the same size, with long text and bounded
+height. The 0.2.11 candidate's APIs require matching installed declarations.
+Disclosure artwork stays subordinate to destination icons without reducing hit
+areas; IconButton.iconSize separates these responsibilities. Compact hints reuse
+Tooltip on the actual Link/button, preserve refs and event handlers, and disappear
+when a branch flyout opens. Pane-toggle glyphs change with accepted visibility.
+
+Material context is part of the family contract. Compare actions, fields,
+choices, selection and supporting elements on the same material. A shared
+semantic context should correct the family together; a descendant-only button
+override leaves fields and composed controls inconsistent. Keep absolute
+material colors separate from contextual control roles and verify the nearest
+nested owner resets those roles. Preserve accent focus and destructive meaning.
+
+BulkActionBar is a one-row capsule for a small set of selection commands. Keep
+one to three visible commands, prefer two, and disclose the remainder through
+its overflow owner. Do not wrap this floating rail into a second row or use it
+as another general toolbar. The host owns selected IDs, confirmation, accepted
+updates, positioning and scroll clearance.
+BulkActionBar counter can be label, number or none. Visible counters reserve
+their width across count changes; choose counterWidth for the expected localized
+summary rather than sizing it from each current count. Hiding it removes its slot.
+
+CollectionToolbar composes the search, Tag, Button and Popover families without
+adding a surface. Use normal Tab navigation for this mixed input/action group.
+Compare SearchInput and existing collection controls at the same controlSize;
+preserve the end anchor, reserved reset space and contextual action colors.
+Keep saved views and query execution in the host; filterContent supplies its draft.
+
+CollectionViewSwitcher composes Select and existing action owners on a separate
+saved-view row. One command uses Button; multiple commands use OverflowActions.
+Use its plain container variant beside peer fields so another material/inset does
+not enlarge the command group. Contained remains appropriate for standalone rails.
+Use the same controlSize and keep Select and action hit areas coherent. Queries,
+dirty-state policy, permissions, dialogs and persistence belong to the host.
+
+FilterGroup composes FilterCondition and existing matching/actions. Preserve
+stable row IDs and accepted controlled state. Addition/removal focus belongs to
+the group after acceptance; Apply/Cancel, validation and query evaluation remain
+host-owned. Do not add a nested material or empty-state narration just because
+the flat group has its own component name.
+
+Render the new control beside its nearest sibling, with the same label/content,
+size, surface and root text scale. Review rest, hover, keyboard focus and the
+states the component actually supports. Include long content, empty/optional
+slots, narrow tracks and enlarged text. The scene is verification tooling, not a
+new runtime wrapper or a mandatory product screen.
+
+Measure what looked wrong: glyph/text centres, visible insets, nested curves,
+focus bounds and overflow thresholds. Exercise resize while an action or popup
+has focus. After a shared-owner correction, inspect another consumer. A green
+build or token reuse alone does not establish visual kinship.
+
+## Keep the contract discoverable
+
+In Flood source, update declarations, component examples, applicable guidance
+and the version decision together; regenerate the existing knowledge catalog.
+In a host, document the project-owned composite and its actual dependencies.
+Do not add unsupported props to examples or a parallel handwritten API index.
+Report executed behavioural/visual checks separately from guidance that was
+merely read. Record deliberate family exceptions instead of making an isolated
+fix the next component's accidental default.
+
+Track actual consumers and interactions for a proposed atom. Demonstrate a shared
+responsibility in different compositions before promoting a recipe helper into
+the package. Do not insert an owner merely to increase its usage count: one
+command can remain Button while a constrained command collection uses
+OverflowActions. Reuse is judged by correct roles and reachable behaviour, not
+the length of an import list.

package/references/composition.md

@@ -138,9 +138,9 @@ Link defaults to text; opt-in solid/subtle/outline/ghost and
 Button sizes share the button recipe without changing native anchor semantics.
 Use href/target for navigation, Button for actions; never nest the two or add
 role=button. Link has no disabled/loading contract. Available in 0.2.3.
-Tabs switches linked content panels (not modes or radio values) on a shared
-contained surface. Avoid a second enclosing card inside the panel; selected fill
-joins the panel without an additional underline. Arrows activate by default,
+Tabs switches linked content panels. Use the default contained variant for a
+shared surface where the selected fill joins the panel. Use variant="line" for
+page-level sections whose content sits on the page canvas. Arrows activate by default,
 or focus only with activationMode=manual; Enter/Space commit. One tab
 stop, RTL/orientation aware, disabled skip. Panels stay mounted/hidden and retain
 native form constraints. Controlled/missing/disabled selected values derive first
@@ -278,4 +278,4 @@ Section headingLevel controls native h2–h6 semantics. Its independent headingS
 uses the existing Heading roles (section/page/large/display), defaulting to section.
 Keep document hierarchy meaningful when changing visual emphasis.
 
-For a command palette, compose Dialog and CommandList. The host owns commands, permissions, query reset and shortcuts; keep Escape available to the dialog. Avoid a duplicate modal or command-search engine. The project recipe lives in docs/recipes/command-palette.md in the source repository.
+Use CommandPalette for modal navigation and command search. The host owns commands, permissions, controlled query reset and shortcuts. Keep CommandList for inline search. The project recipe lives in docs/recipes/command-palette.md in the source repository.