stillmade-sdk 0.1.41 → 0.1.43

package/docs/tools/block-remix.md

@@ -0,0 +1,211 @@
+# Remixing a Block
+
+# Remixing a Block
+
+A remix is an independent Block with a new package identity and version `0.1.0`.
+The original release, installed pins and saved projects remain intact. Remixes
+use the ordinary Block Builder, validator, package format and release pipeline.
+Project Types, projects and generated outputs are outside this workflow.
+
+## Find before you build
+
+Check what already exists before writing a new Block. Create runs a free check
+before every new build, and MCP clients call `find_existing_blocks`. Both search
+reviewed Marketplace listings, tested Community Blocks, built-ins and your own
+Blocks by what they take in, produce and call, and by name. The answer is one of:
+use an existing Block, open your own, remix a close one, chain existing Blocks
+and build only the missing step, or build new. Over MCP, `begin_block_remix`
+starts a remix from an exact public version.
+
+Publishing a renamed copy of another creator's public Block is refused; remix it
+so its license, notices and creator credit stay attached. Max accounts can keep
+such a copy private.
+
+## Required for every finished Block
+
+Automatic remixing is a minimum admission requirement, including private Blocks.
+A creator does not implement a Remix button, callback, endpoint or separate export.
+StillMade derives Remix from the same self-contained package that it installs.
+
+The finished package must contain its editable implementation or declarative
+workflow, typed inputs/outputs, interface schema, permissions, fixtures and legal
+evidence. Declare a supported permissive `manifest.license` and retain the full
+original copyright/license text in `manifest.provenance.notice`; portable packages
+retain their verified source files and generated attribution instead. Do not invent
+copyright holders, repository commits or permission. Unresolved rights produce a
+blocked result. Never silently license someone else's source.
+
+Remixing is enabled by default. An explicit `remixPolicy` must permit remixing
+and must not set `sourceInspection: "no"`. A Block's code is private to its creator: no one else views or downloads it,
+and others change it only by describing changes to StillMade's AI builder.
+Omit optional settings when defaults
+are sufficient. The host creates the new identity, preserves the parent digest,
+source and notices, and presents the ordinary builder. Creators need no extra
+StillMade instructions. Project Edit retains compatible inputs and saved state;
+incompatible changes are reviewed before adoption.
+
+`packages/block-sdk/remix-policy.js` exports `blockRemixPolicy` and
+`assertRemixReady`. SDK `scanPackage` and `admitPackage`, server import, and
+builder completion apply the same **Remix readiness** check. CLI `validate`,
+`test` and `pack` refuse a Block that fails it. Fix the returned diagnostics
+before returning an artifact. Run the normal security, fixture and preview
+checks too; passing remix readiness alone does not certify the whole Block.
+
+Low-level `validatePackage` checks draft structure; it is not a completion or
+installation certificate. Drafts can remain incomplete and editable. Previously
+installed releases are not rewritten or disabled by this new admission rule.
+Protected starting Chat remains protected. Legacy host workspaces do not become
+remixable merely by adding metadata: they need an independent SDK implementation.
+
+## In StillMade
+
+Choose **Remix Block** on an exact public Block version, or **Remix this version**
+in Marketplace. Sign in, review its license and declared permissions, then
+confirm **Remix Block**. The code is never shown or downloadable; describe the
+change you want and StillMade's AI builder makes it. StillMade saves an account draft and opens Create.
+Nothing is installed, published, executed or charged by creating the draft.
+AI refinement edits the implementation, controls and fixtures while the host
+retains and restores immutable source evidence and ancestry. Evidence is not
+charged against the editable-source prompt limit; the package size limit still
+applies. The resulting local Block receives the same admission checks as a
+portable artifact.
+The Versions tab shows ancestry and retained notices. Publishing the edited
+Block requires the normal validation and rights confirmation. A remix of someone
+else's Block is released as a Block owned by the original creator, who keeps its
+code and earns from it; the remixer is credited and can use it right away. A
+remix is always available by link, never private.
+Public Block pages link to paginated newest and top remixes of that exact version.
+Top uses qualified production account counts for a 30-day window, hidden below
+ten accounts and rounded down to tens. Both views fall back to newest when
+analytics is unavailable. Contract differences use the same deterministic
+comparison as Creator. These observations do not claim performance improvements. Follow
+any remix on its listing; existing Creator reports provide incoming/outgoing
+remixes and usage comparisons. Ancestry alone never creates a payout entitlement.
+
+Account creation pins the parent release id, version and digest on the server.
+A retry of the same request returns the current draft instead of creating a
+second copy or overwriting edits. Checkpoints and releases retain inherited
+attribution; removing it requires a separate rights review, not a source edit.
+
+## Outside StillMade
+
+Outside StillMade you remix only your own Blocks: one you imported or built, including a
+newer version you edited in StillMade and downloaded from your versions (**Download
+source + SDK**) to take back to your coding agent. Another person's Block is remixed only
+in StillMade, as above: StillMade offers no download of it, and an import whose original
+is another person's Block is refused with "Their Blocks can be remixed only in StillMade".
+
+Use the CLI shipped in the downloadable SDK:
+
+```sh
+node packages/block-cli/cli.js remix original.stillmade-block my-remix.stillmade-block
+node packages/block-cli/cli.js validate my-remix.stillmade-block
+node packages/block-cli/cli.js test my-remix.stillmade-block
+```
+
+`remix` copies source and fixtures without running the Block. For portable
+packages it also verifies the retained repository evidence. It refuses to
+overwrite an existing output. Its output is an editable draft, not a claim
+that tests passed. Extract/edit a portable package using the canonical layout
+in [PORTABLE.md](PORTABLE.md), then validate, test and pack the finished folder:
+
+```sh
+node packages/block-cli/cli.js pack ./edited-remix ready.stillmade-block
+```
+
+Portable `test` and `pack` use `admitLocalPackage` from
+`packages/block-sdk/local-admission.js`, the same local admission routine as
+StillMade import: static review, isolated fixtures and a sample starting with
+fresh Block state share a 15-second budget. Packaging stops if any check fails.
+`validate` remains a non-executing schema/security and repository-evidence check.
+The packaging result includes the admission report and repository verification.
+StillMade repeats admission and checks current security/account policy at import;
+rendered platform checks remain host checks rather than an offline certification.
+
+Legacy JSON packages can be remixed to `.stillmade.json`. An incomplete legacy
+package cannot acquire portable status merely by changing its file extension.
+Upload the finished package using the existing import review and Install flow.
+Hosted capability and ComfyUI Blocks still require their existing scoped runtime
+approvals; remixing does not authorize provider calls or waive their charges.
+
+## Contract and licensing
+
+The shared transformation is `packages/block-platform/block-remix.js`. Its
+`blockRemixPolicy` and `remixBlock` are used by account creation, local Block
+editing and the SDK CLI. Copies retain code/wrappers, typed I/O, UI, state
+schemas, dependencies, configuration, permissions, tests and legal evidence.
+No installed user state, credentials, listing purchase prices or execution
+approvals are copied. Those belong to the host, outside the source package.
+
+`manifest.provenance.remixSource` retains the complete original Block as inert
+JSON data. Its digest must match the immediate parent pin. The SDK and server
+verify these bytes and inherited legal metadata without executing the original
+or asking the user for a separate source upload. The snapshot counts toward the
+existing 4 MB package and bounded nesting limits. Older packages without a
+snapshot require a matching source already retained by StillMade; immutable
+published packages and installed hashes are not rewritten. Source-byte
+verification is not proof of a creator's legal identity or an earnings claim.
+
+`manifest.provenance.remixedFrom` is the immediate `{id, version, digest}` pin;
+`remixAncestors` retains earlier pins (maximum 64). All digests are lowercase
+SHA-256. Portable packages additionally retain `portable.lineage.parents`
+(maximum 16), a change description, every original evidence file, source commit,
+license and generated NOTICE. Existing provenance is preserved, and a generated
+summary receipt is removed because it describes the original source digest.
+
+Automatic remixing uses the existing conservative portable license profile:
+MIT, BSD-2-Clause, BSD-3-Clause, ISC and Apache-2.0 with retained evidence. For
+nonportable third-party source, the original full license/copyright notice must
+be retained in `manifest.provenance.notice`; a license label alone is insufficient.
+Account ownership does not substitute for retained license evidence.
+
+A portable remix may add another licensed capability or bundled dependency.
+Supported permissive licenses combine using the sorted SPDX `AND` declaration
+generated by `withPortableAttribution`; all inherited licenses remain included.
+Marketplace review uses this same evidence check in the publishing dialog and
+on the server. An “Includes MIT” discovery filter also finds supported declarations
+such as `Apache-2.0 AND MIT`; listings retain the complete declaration. Filtering
+is not evidence verification or permission to redistribute. Unsupported choices,
+exceptions and combinations do not match a constituent permissive filter.
+Append its record to `portable.sources` and its exact evidence files under the
+next `upstream/SOURCE_INDEX/` directory. Keep every inherited source record in
+its original position and preserve every inherited evidence file byte for byte.
+Regenerate `manifest.provenance.portableSources` and `notice` with
+`withPortableAttribution` from `packages/block-sdk/portable.js`; packaging writes
+the matching root NOTICE automatically. Additional sources receive the same
+license and repository-evidence checks as an original portable Block, including
+the supported permissive combination policy and file/size limits. The original snapshot
+and all inherited lineage pins remain unchanged. New behavior still needs its
+own fixtures and the ordinary validation and sandbox review before installation.
+Unsupported combinations, custom, copyleft or unresolved terms return a restricted result pending
+review. This automatic policy does not claim those licenses forbid derivatives.
+
+Historical releases may contain `allowRemixing: false`. Their upstream license
+rights remain intact, but a new finished Block with that setting fails admission.
+Private sharing controls who can access a Block, not whether its authorized
+recipient receives the implementation required for remixing. Starting Chat and
+host-coupled workspaces retain their existing restrictions.
+
+## Acceptance checklist
+
+- **Remix readiness passes** with source and license evidence; no disabled remix or hidden-source setting.
+- New identity and version, original release unchanged, copy saved as a draft.
+- Original implementation, typed contract, UI and fixtures retained.
+- Immediate parent and earlier ancestry pinned, notices and source evidence kept.
+- License/security/access restrictions produce an actionable blocked result.
+- External validation and tests pass before a final package is returned.
+- Normal sandbox, permissions, visibility and install checks remain in force.
+- No payments, ancestor revenue allocation or provider dispatch during remix.
+
+
+## Code stays private
+
+A Block's code is private to its creator. Nobody else can view or download it:
+public pages, Marketplace and remixes never show it, and the source download
+works only for its creator and StillMade admins. An older `sourceInspection: "no"`
+still keeps that Block's releases private and its remix action off. Account and team visibility still determine who may use a
+private package.
+
+A source-access choice cannot replace legal evidence or revoke upstream rights.
+Existing immutable releases keep their established pins and access. Newly finished
+versions must pass the required remix, license and normal admission checks.