stillmade-sdk 0.1.33 → 0.1.35

package/AGENTS.md

@@ -6,7 +6,7 @@ This folder is the StillMade Block SDK. Read this file before writing code; it i
 
 Do not tell the user a Block is ready, done or working until `node packages/block-cli/cli.js gate .` passes after your last edit, and report the exact status it prints. In this folder Claude Code (`.claude/settings.json`) and Cursor (`.cursor/hooks.json`) run the gate when you finish a turn and send any failures back to you, but only in a session started in this folder: if you downloaded the SDK during the current session, run the gate yourself. Other agents must also run it themselves. A module Block runs code, so the gate a hook starts does not run it and says so: run `gate` or `ready` on it yourself. If you cannot fix a failure, say plainly that the Block is not ready and list the failing checks.
 
-Contract `stillmade.block-builder@1.7.0`. Humans, coding agents, imported source, GitHub repositories and generated code all adapt to the Block platform; anything that becomes a StillMade Block obeys this contract.
+Contract `stillmade.block-builder@1.7.1`. Humans, coding agents, imported source, GitHub repositories and generated code all adapt to the Block platform; anything that becomes a StillMade Block obeys this contract.
 
 ## Source of truth
 
@@ -54,7 +54,7 @@ Prefer, in order: an SDK capability; a documented host capability (the hosted op
 
 ## No hidden workarounds
 
-Never make a Block look functional through hard-coded local paths, developer-machine dependencies, undocumented environment variables, admin or database access, hidden core modifications, direct database writes, fake or mocked production results, hand-prepared test assets that hide incompatibilities, credentials in code, or assumptions about one user's machine. The finished Block must work through the same interfaces available to any installed Block; `permissions.network`, `permissions.filesystem` and `permissions.secrets` must be empty arrays.
+Never make a Block look functional through hard-coded local paths, developer-machine dependencies, undocumented environment variables, admin or database access, hidden core modifications, direct database writes, fake or mocked production results, hand-prepared test assets that hide incompatibilities, credentials in code, or assumptions about one user's machine. The finished Block must work through the same interfaces available to any installed Block; `permissions.filesystem` and `permissions.secrets` must be empty arrays, and so must `permissions.network`, except in a module Block, which lists the https origins it calls through `stillmade.net.fetch`.
 
 ## Name it briefly
 

package/PASTE_TO_LLM.md

@@ -2,9 +2,9 @@
 
 <!-- builder-contract:start (generated by npm run build:sdk; do not edit) -->
 
-## Block builder contract (stillmade.block-builder@1.7.0)
+## Block builder contract (stillmade.block-builder@1.7.1)
 
-Contract `stillmade.block-builder@1.7.0`. Humans, coding agents, imported source, GitHub repositories and generated code all adapt to the Block platform; anything that becomes a StillMade Block obeys this contract.
+Contract `stillmade.block-builder@1.7.1`. Humans, coding agents, imported source, GitHub repositories and generated code all adapt to the Block platform; anything that becomes a StillMade Block obeys this contract.
 
 ### Source of truth
 
@@ -52,7 +52,7 @@ Prefer, in order: an SDK capability; a documented host capability (the hosted op
 
 ### No hidden workarounds
 
-Never make a Block look functional through hard-coded local paths, developer-machine dependencies, undocumented environment variables, admin or database access, hidden core modifications, direct database writes, fake or mocked production results, hand-prepared test assets that hide incompatibilities, credentials in code, or assumptions about one user's machine. The finished Block must work through the same interfaces available to any installed Block; `permissions.network`, `permissions.filesystem` and `permissions.secrets` must be empty arrays.
+Never make a Block look functional through hard-coded local paths, developer-machine dependencies, undocumented environment variables, admin or database access, hidden core modifications, direct database writes, fake or mocked production results, hand-prepared test assets that hide incompatibilities, credentials in code, or assumptions about one user's machine. The finished Block must work through the same interfaces available to any installed Block; `permissions.filesystem` and `permissions.secrets` must be empty arrays, and so must `permissions.network`, except in a module Block, which lists the https origins it calls through `stillmade.net.fetch`.
 
 ### Name it briefly
 

package/SDK.md

@@ -182,7 +182,7 @@ The archive needs Node.js 22 or later and nothing else; its runtime is bundled,
 
 ## Block builder contract
 
-Contract `stillmade.block-builder@1.7.0`. Humans, coding agents, imported source, GitHub repositories and generated code all adapt to the Block platform; anything that becomes a StillMade Block obeys this contract.
+Contract `stillmade.block-builder@1.7.1`. Humans, coding agents, imported source, GitHub repositories and generated code all adapt to the Block platform; anything that becomes a StillMade Block obeys this contract.
 
 ### Source of truth
 
@@ -230,7 +230,7 @@ Prefer, in order: an SDK capability; a documented host capability (the hosted op
 
 ### No hidden workarounds
 
-Never make a Block look functional through hard-coded local paths, developer-machine dependencies, undocumented environment variables, admin or database access, hidden core modifications, direct database writes, fake or mocked production results, hand-prepared test assets that hide incompatibilities, credentials in code, or assumptions about one user's machine. The finished Block must work through the same interfaces available to any installed Block; `permissions.network`, `permissions.filesystem` and `permissions.secrets` must be empty arrays.
+Never make a Block look functional through hard-coded local paths, developer-machine dependencies, undocumented environment variables, admin or database access, hidden core modifications, direct database writes, fake or mocked production results, hand-prepared test assets that hide incompatibilities, credentials in code, or assumptions about one user's machine. The finished Block must work through the same interfaces available to any installed Block; `permissions.filesystem` and `permissions.secrets` must be empty arrays, and so must `permissions.network`, except in a module Block, which lists the https origins it calls through `stillmade.net.fetch`.
 
 ### Name it briefly
 
@@ -7241,9 +7241,9 @@ Ask the assistant to return source files or one `.stillmade.json` package. Run t
 
 <!-- builder-contract:start (generated by npm run build:sdk; do not edit) -->
 
-### Block builder contract (stillmade.block-builder@1.7.0)
+### Block builder contract (stillmade.block-builder@1.7.1)
 
-Contract `stillmade.block-builder@1.7.0`. Humans, coding agents, imported source, GitHub repositories and generated code all adapt to the Block platform; anything that becomes a StillMade Block obeys this contract.
+Contract `stillmade.block-builder@1.7.1`. Humans, coding agents, imported source, GitHub repositories and generated code all adapt to the Block platform; anything that becomes a StillMade Block obeys this contract.
 
 ### Source of truth
 
@@ -7291,7 +7291,7 @@ Prefer, in order: an SDK capability; a documented host capability (the hosted op
 
 ### No hidden workarounds
 
-Never make a Block look functional through hard-coded local paths, developer-machine dependencies, undocumented environment variables, admin or database access, hidden core modifications, direct database writes, fake or mocked production results, hand-prepared test assets that hide incompatibilities, credentials in code, or assumptions about one user's machine. The finished Block must work through the same interfaces available to any installed Block; `permissions.network`, `permissions.filesystem` and `permissions.secrets` must be empty arrays.
+Never make a Block look functional through hard-coded local paths, developer-machine dependencies, undocumented environment variables, admin or database access, hidden core modifications, direct database writes, fake or mocked production results, hand-prepared test assets that hide incompatibilities, credentials in code, or assumptions about one user's machine. The finished Block must work through the same interfaces available to any installed Block; `permissions.filesystem` and `permissions.secrets` must be empty arrays, and so must `permissions.network`, except in a module Block, which lists the https origins it calls through `stillmade.net.fetch`.
 
 ### Name it briefly
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stillmade-sdk",
-  "version": "0.1.33",
+  "version": "0.1.35",
   "description": "StillMade Block SDK, CLI and examples",
   "license": "PolyForm-Shield-1.0.0",
   "type": "module",

package/packages/block-sdk/builder-contract.js

@@ -9,7 +9,7 @@
 import {HOSTED_OPERATION_NAMES} from './contracts.js';
 
 export const BUILDER_CONTRACT_ID='stillmade.block-builder';
-export const BUILDER_CONTRACT_VERSION='1.7.0';
+export const BUILDER_CONTRACT_VERSION='1.7.1';
 export const BUILDER_CONTRACT_STAMP=`${BUILDER_CONTRACT_ID}@${BUILDER_CONTRACT_VERSION}`;
 export const BUILDER_CONTRACT_DOCS_PATH='/docs/build/block-builder-contract';
 // Block names appear in step bars, cards and pickers; new releases keep them short.
@@ -56,8 +56,8 @@ const SECTIONS=Object.freeze([
   `Use SDK and host capabilities (hosted operations: ${hostedOperations}) before Block-local code; never rebuild assets, pickers, auth, credits, secrets, permissions, progress, sharing, persistence or providers inside a Block.`,
   `Prefer, in order: an SDK capability; a documented host capability (the hosted operations are ${hostedOperations}; connected third-party apps go through \`connection.execute\`); an approved dependency the SDK already bundles; small Block-local code. Do not duplicate what StillMade provides. A Block never contains its own asset system, file picker, authentication, project-context system, input resolver, Block connection system, credit system, secrets store, permission system, progress system, multiplayer system, persistence system, model-provider abstraction or execution protocol.`),
  rule('no-workarounds','both',
-  'No hard-coded paths, undocumented env vars, database access, core edits, mocked results or credentials; `network`, `filesystem` and `secrets` permissions stay empty.',
-  'Never make a Block look functional through hard-coded local paths, developer-machine dependencies, undocumented environment variables, admin or database access, hidden core modifications, direct database writes, fake or mocked production results, hand-prepared test assets that hide incompatibilities, credentials in code, or assumptions about one user\'s machine. The finished Block must work through the same interfaces available to any installed Block; `permissions.network`, `permissions.filesystem` and `permissions.secrets` must be empty arrays.'),
+  'No hard-coded paths, undocumented env vars, database access, core edits, mocked results or credentials; `network` (except module Blocks), `filesystem` and `secrets` stay empty.',
+  'Never make a Block look functional through hard-coded local paths, developer-machine dependencies, undocumented environment variables, admin or database access, hidden core modifications, direct database writes, fake or mocked production results, hand-prepared test assets that hide incompatibilities, credentials in code, or assumptions about one user\'s machine. The finished Block must work through the same interfaces available to any installed Block; `permissions.filesystem` and `permissions.secrets` must be empty arrays, and so must `permissions.network`, except in a module Block, which lists the https origins it calls through `stillmade.net.fetch`.'),
  rule('naming','block',
   `Name the Block in ${BLOCK_NAME_MAX_LENGTH} characters or fewer, in plain words.`,
   `Give the Block a short, plain name of ${BLOCK_NAME_MAX_LENGTH} characters or fewer that says what it does ("Captioned Clip", not "Captioned Business Clip Generator With Review"). The name appears in step bars, Project Type cards and pickers, so put the detail in the description instead. New releases with a longer name do not pass readiness.`),

package/packages/block-sdk/schema-fields.js

@@ -15,13 +15,21 @@ export function createSchemaFields(lockedInputKeys=[]) {
  function read(root,path){pathCheck(path);inert(root);let item=root;for(const key of path){if(!item||typeof item!=='object'||!Object.hasOwn(item,key))return undefined;item=item[key];}return item===undefined?undefined:copy(item);}
  function set(root,path,value){pathCheck(path);const result=copy(root);inert(value);let item=result;for(let i=0;i<path.length-1;i++){const key=path[i];if(!Object.hasOwn(item,key)||item[key]===null||typeof item[key]!=='object')item[key]=typeof path[i+1]==='number'?[]:{};item=item[key];}item[path.at(-1)]=copy(value);return result;}
  function empty(s){if(Object.hasOwn(s,'default'))return copy(s.default);if(Array.isArray(s.enum)&&s.enum.length)return copy(s.enum[0]);return s.type==='object'?{}:s.type==='array'?[]:s.type==='boolean'?false:['integer','number'].includes(s.type)?Math.max(s.minimum||0,0):'';}
+ function hint(description){
+  const text=typeof description==='string'?description.replace(/\s+/g,' ').trim():'';if(!text)return '';
+  const [first,second]=text.split(/(?<=[.!?])\s+(?=[A-Z])/);
+  const kept=second&&first.length+second.length<280?first+' '+second:first;
+  return kept.length>280?kept.slice(0,279).trimEnd()+'…':kept;
+ }
  function controls(schema,bindings,values,{canEdit=true,busy=false}={}) {
   inert(schema);inert(bindings);inert(values);let count=0;const tree=[],actions=[];
   const action=(kind,path,s)=>{const id=`field-${actions.length}`;actions.push({id,kind,path,s});return id;};
   function fields(s,path,value,label,required,depth) {
    if(++count>150||depth>5)return [{tag:'p',text:'This task needs a custom interface for its remaining fields.'}];
-   const result=[{tag:'label',text:String(label).slice(0,240)+(required?' *':' (optional)')}],disabled=busy||!canEdit||locked.has(path[0]);
-   if(s.description)result.push({tag:'small',text:String(s.description).slice(0,1000)});
+   // A description sits behind an (i) beside its label, one or two sentences:
+   // connected apps describe fields at length for AI models, not people.
+   const name=String(label).slice(0,240)+(required?' *':' (optional)'),about=hint(s.description);
+   const result=[about?{tag:'div',className:'sm-label',children:[{tag:'label',text:name},{tag:'details',className:'sm-hint',children:[{tag:'summary',label:'About '+String(label).slice(0,200)},{tag:'p',text:about}]}]}:{tag:'label',text:name}],disabled=busy||!canEdit||locked.has(path[0]);
    if(s.type==='object'&&s.properties){for(const key of Object.keys(s.properties))result.push({tag:'section',children:fields(s.properties[key],path.concat(key),value?.[key],s.properties[key].title||key,(s.required||[]).includes(key),depth+1)});}
    else if(s.type==='array'){
     const rows=Array.isArray(value)?value:[];