@flood-md/agent 0.2.8 → 0.2.10

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",
@@ -56,9 +61,94 @@
       "source": "references/flood-composition/SKILL.md",
       "target": ".agents/skills/flood-ui/references/flood-composition/SKILL.md",
       "kind": "skill"
+    },
+    {
+      "source": "workflows.json",
+      "target": ".agents/skills/flood-ui/workflows.json",
+      "kind": "reference"
+    },
+    {
+      "source": "references/flood-spacing/SKILL.md",
+      "target": ".agents/skills/flood-ui/references/flood-spacing/SKILL.md",
+      "kind": "skill"
+    },
+    {
+      "source": "references/flood-foundations/SKILL.md",
+      "target": ".agents/skills/flood-ui/references/flood-foundations/SKILL.md",
+      "kind": "skill"
+    },
+    {
+      "source": "references/flood-accessibility/SKILL.md",
+      "target": ".agents/skills/flood-ui/references/flood-accessibility/SKILL.md",
+      "kind": "skill"
+    },
+    {
+      "source": "references/flood-forms/SKILL.md",
+      "target": ".agents/skills/flood-ui/references/flood-forms/SKILL.md",
+      "kind": "skill"
+    },
+    {
+      "source": "references/flood-overlays/SKILL.md",
+      "target": ".agents/skills/flood-ui/references/flood-overlays/SKILL.md",
+      "kind": "skill"
+    },
+    {
+      "source": "references/flood-navigation/SKILL.md",
+      "target": ".agents/skills/flood-ui/references/flood-navigation/SKILL.md",
+      "kind": "skill"
+    },
+    {
+      "source": "references/flood-data-display/SKILL.md",
+      "target": ".agents/skills/flood-ui/references/flood-data-display/SKILL.md",
+      "kind": "skill"
+    },
+    {
+      "source": "references/flood-feedback/SKILL.md",
+      "target": ".agents/skills/flood-ui/references/flood-feedback/SKILL.md",
+      "kind": "skill"
+    },
+    {
+      "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"
     }
   ],
-  "version": "0.2.8",
+  "version": "0.2.10",
   "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.8",
+  "version": "0.2.10",
   "type": "module",
   "description": "Versioned Flood design instructions for coding agents.",
   "license": "MIT",
@@ -13,15 +13,23 @@
     "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",
     "./rules.json": "./rules.json",
+    "./workflows.json": "./workflows.json",
     "./references/*": "./references/*"
   },
   "publishConfig": {

package/references/flood-accessibility/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: flood-accessibility
+description: Review Flood interface names, keyboard flow, focus, perception and reflow in the actual host. Use for interaction or accessibility acceptance.
+---
+
+# Review an actual task
+
+Use [accessibility](../accessibility.md) and the installed component's contract.
+A scanner result is supporting evidence, not certification of an application.
+
+## Trace the task from entry to completion
+
+- Identify the name, role, state and instruction for each actionable control.
+  Retain native semantics before adding ARIA. A placeholder, color or tooltip
+  alone is not an adequate field name or required instruction.
+- If a visible label is intentionally hidden, preserve the supplied label/legend
+  through the supported API and verify its contextual meaning and focus reveal.
+  Do not remove the label or invent unsupported hideLabel props on bare controls.
+- Complete the task with keyboard only, including reverse navigation, cancel,
+  invalid submission and recovery. Distinguish roving focus, selection and
+  activation; arrow behavior follows the specific component contract.
+- After pointer activation of a custom keyboard-owning control, inspect actual
+  focus before testing keys. Some browsers do not mouse-focus native buttons;
+  a custom combobox cannot rely on that default. Preserve an intentional focus
+  move made by the host callback rather than forcing focus back afterward.
+- Check the accent focus perimeter in combinations with invalid, selected and
+  read-only states. It must remain visible without changing layout or hiding
+  beneath a rail, sticky region or overlay. Closing an overlay returns focus
+  appropriately without overriding a deliberate host focus move.
+- Evaluate text with its actual size, weight and composited background using
+  applicable WCAG checks and supplementary APCA guidance. Decorative lines are
+  different from necessary control/state indicators; do not relabel a necessary
+  cue as decoration to avoid checking it. APCA is not WCAG conformance.
+- Exercise narrow width, root text enlargement, long content, RTL where supported,
+  forced colors and the existing reduced-motion fallback. These checks do not
+  introduce new animation or theme requirements.
+
+For assistive-technology announcements, inspect live-region semantics and test
+with the actual technology when available. Do not report audible announcements
+from a DOM role alone. Record any device/technology that was not tested.

package/references/flood-composition/SKILL.md

@@ -10,6 +10,11 @@ components. Preserve their anatomy and behavior when improving a composition.
 Read the governing project instructions, matching declarations and relevant
 component guide first. This skill grants no additional permissions.
 
+When introducing visible interface text, apply the
+[interface content skill](../flood-interface-content/SKILL.md) before filling
+optional headings, descriptions or helper slots. Existing user-authored content
+is not permission to rewrite it during an unrelated layout correction.
+
 ## Choose the smallest existing owner
 
 Before changing JSX, identify the visible roles and their existing owners:
@@ -18,6 +23,31 @@ metadata, IconButton for an icon action, Dialog for modal behavior, Text/Heading
 for typography, and the appropriate form, list or table primitive for semantics.
 Check the actual installed exports and props; do not invent APIs from newer docs.
 
+Search the installed catalog by the role before settling on a low-level building
+block. Read the selected contract and compare a more specific owner when one
+exists: Metric for a labelled statistic; DatePicker for ordinary date selection
+with typing and a calendar, DateField for an explicitly entry-only interaction;
+StatusIndicator for a named state. Input type="date"
+invokes the browser's picker, not Flood's Calendar. Use it only for an explicit
+native-picker requirement or a documented limitation of the installed controls.
+Heading/Text remain valid for ordinary prose, not a default replacement for an
+available statistic component.
+
+Include layout and secondary interactions in that selection: Grid for repeated
+form tracks, Stack/Inline for related layout, AlertDialog for a discard/delete
+confirmation, and Alert/StatusIndicator for the appropriate feedback role.
+window.confirm/alert/prompt are browser UI, not Flood components. A small scope
+does not justify replacing an available owner with native UI or a parallel CSS
+grid. Keep native form, table and semantic document/shell elements where they
+supply structure; styling the host shell is different from reimplementing a
+provided layout or control. Document a genuine missing capability before using
+a project-owned adapter.
+
+Record the selected owner and any rejected match before implementing the surface.
+If discovery finds no suitable component, state the missing capability; do not
+claim that the library has no owner without checking. Keep this decision record
+in development notes, never as extra explanatory text in the product.
+
 - Reuse the matching component with its supported props and tokens.
 - If spacing or alignment is wrong, inspect both the primitive and the parent
   composition. Fix the owner of the relationship. Keep the primitive intact.